# Build Agents on Cloudflare
URL: https://developers.cloudflare.com/agents/
import {
CardGrid,
Description,
Feature,
LinkButton,
LinkTitleCard,
PackageManagers,
Plan,
RelatedProduct,
Render,
TabItem,
Tabs,
} from "~/components";
Build and deploy AI-powered Agents on Cloudflare that can autonomously perform tasks, communicate with clients in real time, persist state, execute long-running and repeat tasks on a schedule, send emails, run asynchronous workflows, browse the web, query data from your Postgres database, call AI models, support human-in-the-loop use-cases, and more.
#### Ship your first Agent
Use the agent started template to 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 to build and deploy an Agent to prod.
If you're already building on [Workers](/workers/), you can install the `agents-sdk` package directly into an existing project:
```sh
npm i agents-sdk
```
Dive into the [Agent SDK reference](/agents/api-reference/sdk/) 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/examples/manage-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/examples/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/examples/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/examples/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 />
---
# 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"]}
/>
---
# Get 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/configuration/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/integrations/aig-workers-ai-binding/)
- [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/providers/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.
---
# Overview
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>
---
# Changelog
URL: https://developers.cloudflare.com/browser-rendering/changelog/
import { ProductReleaseNotes } from "~/components";
{/* <!-- Actual content lives in /src/content/release-notes/radar.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.
##### Uncaught (in response) TypeError: Cannot read properties of undefined (reading 'fetch')
Make sure that you are passing your Browser binding to the `puppeteer.launch` api and that you have [Workers for Platforms Paid plan](/cloudflare-for-platforms/workers-for-platforms/platform/pricing/).
##### Will browser rendering bypass Cloudflare's Bot Protection?
Browser rendering requests are always identified as bots by Cloudflare.
If you are trying to **scan** your **own zone**, you can create a [WAF skip rule](/waf/custom-rules/skip/) to bypass the bot protection using a header or a custom user agent.
## Puppeteer
##### Code generation from strings disallowed for this context while using an Xpath selector
Currently it's 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.
:::
---
# Get started
URL: https://developers.cloudflare.com/browser-rendering/get-started/
Browser rendering can be used in two ways:
- [Workers Binding API](/browser-rendering/workers-binding-api) 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/).
</Description>
<Plan type="workers-paid" />
The Workers Browser Rendering API allows developers to programmatically control and interact with a headless browser instance and create automation flows for their applications and products. Once you configure the service, Workers Browser Rendering gives you access to a WebSocket endpoint that speaks the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). DevTools is what allows Cloudflare to instrument a Chromium instance running in the Cloudflare global network.
Use Browser Rendering to:
- Take screenshots of pages.
- Convert a page to a PDF.
- Test web applications.
- Gather page load performance metrics.
- Crawl web pages for information retrieval.
## 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>
## 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>
---
# Calls vs regular SFUs
URL: https://developers.cloudflare.com/calls/calls-vs-sfus/
## Cloudflare Calls vs. Traditional SFUs
Cloudflare Calls 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. Calls 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 Calls different?
Cloudflare Calls addresses these limitations by leveraging Cloudflare's global network infrastructure:
* **Global Distribution Without Regions:** Unlike traditional SFUs, Cloudflare Calls 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 Calls. Every server within Cloudflare's network contributes to handling Calls, 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 Calls 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 Calls 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 Calls 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 Calls 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 Calls
Integrating Cloudflare Calls 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/calls/changelog/
import { ProductReleaseNotes } from "~/components";
{/* <!-- Actual content lives in /src/content/release-notes/calls.yaml. --> */}
<ProductReleaseNotes />
---
# DataChannels
URL: https://developers.cloudflare.com/calls/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 Calls SFU]
B -->|Arbitrary data| C@{ shape: procs, label: "Subscribers"}
```
DataChannels on Cloudflare Calls 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 a two Calls 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 Calls 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 Calls 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 [Calls Examples github repo](https://github.com/cloudflare/calls-examples/tree/main/echo-datachannels).
---
# Demos
URL: https://developers.cloudflare.com/calls/demos/
import { ExternalResources, GlossaryTooltip } from "~/components"
Learn how you can use Calls within your existing architecture.
## Demos
Explore the following <GlossaryTooltip term="demo application">demo applications</GlossaryTooltip> for Calls.
<ExternalResources type="apps" products={["Calls"]} />
---
# Quickstart guide
URL: https://developers.cloudflare.com/calls/get-started/
:::note[Before you get started:]
You must first [create a Cloudflare account](/fundamentals/setup/account/create-account/).
:::
## Create your first app
Every Calls 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 Calls App. When you create a Calls App, you will get:
* App ID
* App Secret
These two combined will allow you to make API Calls from your backend server to Calls.
---
# Example architecture
URL: https://developers.cloudflare.com/calls/example-architecture/
<div class="full-img">
</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 Calls API to pass the SDP from the clients to establish the WebRTC connection.
4. Calls API relays back the Calls 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.
---
# Connection API
URL: https://developers.cloudflare.com/calls/https-api/
Cloudflare Calls 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 Calls, 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)](/calls/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 Calls is designed to operate efficiently without the need for TURN servers in most scenarios, as Cloudflare exposes a publicly routable IP address for Calls. 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 Calls 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 Calls 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
```
---
# Overview
URL: https://developers.cloudflare.com/calls/
import { Description, LinkButton } from "~/components";
<Description>
Build real-time serverless video, audio and data applications.
</Description>
Cloudflare Calls 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 Calls runs on [Cloudflare's global cloud network](https://www.cloudflare.com/network/) in hundreds of cities worldwide.
<LinkButton variant="primary" href="/calls/get-started/">
Get started
</LinkButton>
<LinkButton
variant="secondary"
href="https://dash.cloudflare.com/?to=/:account/calls"
>
Calls dashboard
</LinkButton>
<LinkButton variant="secondary" href="https://github.com/cloudflare/orange">
Orange Meets demo app
</LinkButton>
---
# Introduction
URL: https://developers.cloudflare.com/calls/introduction/
Cloudflare Calls can be used to add realtime audio, video and data into your applications. Cloudflare Calls uses WebRTC, which is the lowest latency way to communicate across a broad range of platforms like browsers, mobile and native apps.
Calls integrates with your backend and frontend application to add realtime functionality.
## Why Cloudflare Calls exists
* **It's 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 don't 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 Calls 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 mature and well understood.
## What makes Cloudflare Calls unique
* \**Unopinionated*: Cloudflare Calls 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 Calls 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 Calls to solve scalability issues with your SFU. You can use in combination with peer-to-peer architecture. You can use Cloudflare Calls standalone. To what extent you use Cloudflare Calls is up to you.
## What exactly does Cloudflare Calls do?
* **SFU**: Calls 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 Calls 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 Calls. 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 Calls App or from [demos](/calls/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's your responsibility to save and distribute this ID.
:::note[Calls is not a presence protocol]
Calls does not know what a room is. It only knows media tracks. It's 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've got yourself a video conference!
:::
3. Create an app where you manage each connection to Cloudflare Calls 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](/calls/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.
---
# Limits, timeouts and quotas
URL: https://developers.cloudflare.com/calls/limits/
Understanding the limits and timeouts of Cloudflare Calls 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 Calls 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 Calls 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.
---
# Pricing
URL: https://developers.cloudflare.com/calls/pricing/
Cloudflare Calls billing is based on data sent from Cloudflare edge to your application.
Cloudflare Calls 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 Calls billing appears as a single line item on your Cloudflare bill, covering both SFU and TURN.
Traffic between Cloudflare Calls TURN and Cloudflare Calls 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](/calls/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.
---
# Sessions and Tracks
URL: https://developers.cloudflare.com/calls/sessions-tracks/
Cloudflare Calls 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 Calls.
## Application
A Calls 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 Calls usage can be queried at Application, Session or Track level.
## Sessions
A **Session** in Cloudflare Calls 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 Calls a versatile tool for real-time applications. Each track is available globally to be retrieved from any Session within an App.
## Calls as a Programmable "Switchboard"
The analogy of a switchboard is apt for understanding Calls. Historically, switchboard operators connected calls by manually plugging in jacks. Similarly, Calls 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 Calls 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
Calls 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.
---
# Cloudflare for Platforms
URL: https://developers.cloudflare.com/cloudflare-for-platforms/
import { Description, Feature } from "~/components"
<Description>
Cloudflare's offering for SaaS businesses.
</Description>
Extend Cloudflare's security, reliability, and performance services to your customers with Cloudflare for Platforms. Together with Cloudflare for SaaS and Workers for Platforms, your customers can build custom logic to meet their needs right into your application.
***
## Products
<Feature header="Cloudflare for SaaS" href="/cloudflare-for-platforms/cloudflare-for-saas/">
Cloudflare for SaaS allows you to extend the security and performance benefits of Cloudflare’s network to your customers via their own custom or vanity domains.
</Feature>
<Feature header="Workers for Platforms" href="/cloudflare-for-platforms/workers-for-platforms/">
Workers for Platforms help you deploy serverless functions programmatically on behalf of your customers.
</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>
---
# 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.
## 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"]} />
---
# Get 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 to query 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).
:::
## 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: "Hello World Worker",
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 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 > **Workers & Pages** > **Overview**.
3. Select **Create**.
4. Select **Create Worker**.
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 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 d1` command and give your database a name. In this tutorial, the database is named `prod-d1-tutorial`:
```sh
npx wrangler d1 create prod-d1-tutorial
```
```sh output
✅ Successfully created DB 'prod-d1-tutorial'
[[d1_databases]]
binding = "DB" # available in your Worker on env.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.
:::note
The `wrangler` command-line interface 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.
:::
</TabItem> <TabItem label='Dashboard'>
<Steps>
1. Go to **Storage & Databases** > **D1**.
2. Select **Create**.
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 **Workers & Pages** > **Overview**.
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
### Configure your D1 database
<Tabs syncKey='CLIvDash'> <TabItem label='CLI'>
After correctly preparing your [Wrangler configuration file](/workers/wrangler/configuration/), set up your database. Use the example `schema.sql` file 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
```
3. Validate your data is in your 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 (5f092302-3fbd-4247-a873-bf1afc5150b) 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**.
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 TypeScript 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 define 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 **Workers & Pages** > **Overview**.
2. Select the `d1-tutorial` Worker you created.
3. Select **Edit Code**.
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 database
Deploy your database 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/#configure-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. Bootstrap your database with the `schema.sql` file you created in step 4:
```sh
npx wrangler d1 execute prod-d1-tutorial --remote --file=./schema.sql
```
2. Validate the data is in production by running:
```sh
npx wrangler d1 execute prod-d1-tutorial --remote --command="SELECT * FROM Customers"
```
3. Deploy your Worker to make your project accessible on the Internet. Run:
```sh
npx wrangler deploy
```
```sh output
Outputs: https://d1-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 `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 **Workers & Pages** > **Overview**.
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**.
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>
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 **Workers & Pages** > **Overview**.
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/).
---
# Overview
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 recieving 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";
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.
---
# Changelog
URL: https://developers.cloudflare.com/durable-objects/changelog/
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 />
---
# 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"]} />
---
# Overview
URL: https://developers.cloudflare.com/durable-objects/
import { Render, CardGrid, Description, Feature, LinkTitleCard, Plan, RelatedProduct, LinkButton } from "~/components"
<Description>
Create collaborative applications, real-time chat, multiplayer games and more without needing to coordinate state or manage infrastructure.
</Description>
<Plan type="paid" />
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, and deep distributed systems, without requiring you to build serialization and coordination primitives on your own.
### 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.
<LinkButton href="/durable-objects/get-started/tutorial/">Get started</LinkButton>
:::note[SQLite in Durable Objects Beta]
The new beta version of Durable Objects is available where each Durable Object has a private, embedded SQLite database. When deploying a new Durable Object class, users can [opt-in to a SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend) in order to access new [SQL API](/durable-objects/api/sql-storage/#exec) and [point-in-time-recovery API](/durable-objects/api/sql-storage/#point-in-time-recovery), part of Durable Objects Storage API.
Storage API billing is not enabled for Durable Object classes using SQLite storage backend. SQLite-backed Durable Objects will incur [charges for requests and duration](/durable-objects/platform/pricing/#billing-metrics). We plan to enable Storage API billing for Durable Objects using SQLite storage backend in the first half of 2025 after advance notice with the following [pricing](/durable-objects/platform/pricing/#sqlite-storage-backend).
:::
***
## 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>
---
# 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/#methods) and an [SQL API](/durable-objects/api/sql-storage/).
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 ["Tutorial with SQL API"](/durable-objects/get-started/tutorial-with-sql-api/) 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.
---
# 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.
---
# Overview
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="Area 1 Email Security" href="/email-security/" product="email-security">
Cloudflare Area 1 Email Security is a cloud-native service that stops phishing attacks, the biggest cybersecurity threat, across all threat vectors - email, web, and network - either at the edge or in the cloud.
</RelatedProduct>
<RelatedProduct header="DNS" href="/dns/" product="dns">
Email Routing is available to customers using Cloudflare as an authoritative nameserver.
</RelatedProduct>
---
# 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 signs email on behalf of `email.cloudflare.net`. If the sender did not sign the email, the receiver will likely use Cloudflare's signature for authentication.
Below is the DKIM key for `email.cloudflare.net`:
```sh
dig TXT 2022._domainkey.email.cloudflare.net +short
```
```sh output
"v=DKIM1; h=sha256; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnraPy1d8e6+lzeE1HIoUvYWoAOUSREkNHcwxA/ueVM8f6FKXvPu/9gVpgkn8iUyaCfk2z1MW+OVLuFeH64YRMa39mkaQalgke2tZ05SnjRUtYEHYvfrqPuMT+Ouk+GecpgvrtMq5gMXm6ZfeUhQkdWxmMQJGf4fdW5I0piUQJMhK/Qc1dNRSskk" "TiUtXKnsEdjTN2xcnHhyj985S0xOEAxm9Uj1rykPqVvKpqEdjUkujbXOwR0KmHTvPyFpBjCCfxAVqOwwo9zBYuvk/nh0qlDgLIpy0SimrYhNFCq2XBxIj4tdUzIl7qZ5Ck6zLCQ+rjzJ4sm/zA+Ov9kDkbcmyrwIDAQAB"
```
### 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 hostnames
In addition to the outbound prefixes, Email Routing will use the domain `email.cloudflare.net` for the `HELO/EHLO` command.
PTR records (reverse DNS) ensure that each hostname has an corresponding IP. For example:
```sh
dig a0-7.email.cloudflare.net +short
```
```sh output
104.30.0.7
```
```sh
dig -x 104.30.0.7 +short
```
```sh output
a0-7.email.cloudflare.net.
```
### 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/20`
**IPv6**
`2405:8100:c000::/38`
_Ranges last updated: December 13th, 2023_
### 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.
### Spam and abusive traffic
Handling spam and abusive traffic is essential to any email provider. Email Routing filters emails based on advanced anti-spam criteria, [powered by Email Security (formerly Area 1)](/email-security/). When Email Routing detects and blocks a spam email, you will receive a message with details explaining what happened. For example:
```txt
554 <YOUR_IP_ADDRESS> found on one or more DNSBLs (abusixip). Refer to https://developers.cloudflare.com/email-routing/postmaster/#spam-and-abusive-traffic/
```
### 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/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"]} />
---
# Get started
URL: https://developers.cloudflare.com/hyperdrive/get-started/
import { Render, PackageManagers } 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 can cache 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.
## Prerequisites
:::note[Workers Paid plan required]
Hyperdrive is available to all users on the [Workers Paid plan](/workers/platform/pricing/#workers).
:::
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 [`Node.js`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). 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.
3. Have **a publicly accessible PostgreSQL (or PostgreSQL compatible) database**. Cloudflare recommends [Neon](https://neon.tech/) if you do not have an existing database. Read the [Neon documentation](https://neon.tech/docs/introduction) to create your first 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: "Hello World Worker",
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, including Postgres.js, and needs to be configured for your Workers project.
<Render file="nodejs_compat" product="workers" />
## 3. Connect Hyperdrive to a database
:::note
Hyperdrive currently works with PostgreSQL and PostgreSQL compatible databases, including CockroachDB and Materialize.
Support for other database engines, including MySQL, is on the roadmap.
:::
Hyperdrive works by connecting to your database.
To create your first Hyperdrive database configuration, change into the directory you just created for your Workers project:
```sh
cd hyperdrive-tutorial
```
:::note
Support for the new `hyperdrive` commands in the wrangler CLI requires a wrangler version of `3.10.0` or later. You can use `npx wrangler@latest` to always ensure you are using the latest version of Wrangler.
:::
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`.
Hyperdrive accepts the combination of these parameters in the common connection string format used by database drivers:
```txt
postgres://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name
```
Most database providers will provide a connection string you can directly 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"
```
If successful, the command will output your new Hyperdrive configuration:
```json
{
"id": "<example id: 57b7076f58be42419276f058a8968187>",
"name": "YOUR_CONFIG_NAME",
"origin": {
"host": "YOUR_DATABASE_HOST",
"port": 5432,
"database": "DATABASE",
"user": "DATABASE_USER"
},
"caching": {
"disabled": false
}
}
```
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
### Install a database driver
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 [Postgres.js](https://github.com/porsager/postgres), one of the most widely used PostgreSQL drivers.
To install `postgres`, ensure you are in the `hyperdrive-tutorial` directory. Open your terminal and run the following command:
<PackageManagers pkg="postgres" comment="This should install v3.4.5 or later" />
With the driver installed, you can now create a Worker script that queries your database.
### Write a Worker
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
// Postgres.js 3.4.5 or later is recommended
import postgres from "postgres";
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> {
console.log(JSON.stringify(env));
// Create a database client that connects to your database via Hyperdrive.
//
// Hyperdrive generates a unique connection string you can pass to
// supported drivers, including node-postgres, Postgres.js, and the many
// ORMs and query builders that use these drivers.
const sql = postgres(
env.HYPERDRIVE.connectionString,
{
// 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,
},
);
try {
// Test query
const results = await sql`SELECT * FROM pg_tables`;
// Clean up the client, ensuring we don't kill the worker before that is
// completed.
ctx.waitUntil(sql.end());
// Return result rows as JSON
return Response.json(results);
} 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` that outputs all tables (user and system created) in the database (as an example query).
3. Returns the response as JSON to the client.
## 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).
---
# Overview
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-paid" />
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 database, including those hosted on AWS, Google Cloud and Neon, as well as Postgres-compatible databases like CockroachDB and Timescale, with MySQL coming soon. 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="Workers Binding API">
<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>
<LinkButton href="/hyperdrive/get-started/">Get started</LinkButton>
</TabItem>
</Tabs>
---
## 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/configuration/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="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/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"]} />
---
# Get 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/setup/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.
:::
---
# Overview
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/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"]} />
---
# Get started
URL: https://developers.cloudflare.com/kv/get-started/
import { Render, PackageManagers, Steps, FileTree, Details, Tabs, TabItem, WranglerConfig } 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 CLI or through the Cloudflare dashboard.
## 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: "Hello World Worker",
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 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'>
[Wrangler](/workers/wrangler/) allows you to put, list, get, and delete entries 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 `BINDING_NAME`.
```sh
npx wrangler kv namespace create BINDING_NAME
```
```sh output
🌀 Creating namespace with title kv-tutorial-BINDING_NAME
✨ Success!
Add the following to your configuration file:
[[kv_namespaces]]
binding = "BINDING_NAME"
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>
:::note
:::
</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.
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 = "<BINDING_NAME>"
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_NAME>` is used to reference this KV namespace in your Worker. For this tutorial, this should be `BINDING_NAME`.
- 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.
</Steps>
:::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.
:::
</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.
### 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>"
```
```sh output
Writing the value "<VALUE>" to key "<KEY>" on namespace <BINDING_ID>.
```
</Steps>
Instead of using `--binding`, you can also use `--namespace-id` to specify which KV namespace should receive the operation:
```sh
npx wrangler kv key put --namespace-id=<BINDING_ID> "<KEY>" "<VALUE>"
```
```sh output
Writing the value "<VALUE>" to key "<KEY>" on namespace <BINDING_ID>.
```
To create a key and a value in local mode, add the `--local` flag at the end of the command:
```sh
npx wrangler kv key put --namespace-id=xxxxxxxxxxxxxxxx "<KEY>" "<VALUE>" --local
```
</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>
### Get a value
<Tabs syncKey='CLIvsDash'><TabItem label = 'CLI'>
To access the value using Wrangler:
<Steps>
1. Run the `wrangler kv key get` subcommand in your terminal, and input your key value:
```sh
# Replace [OPTIONS] with --binding or --namespace-id
npx wrangler kv key get [OPTIONS] "<KEY>"
```
A KV namespace can be specified in two ways:
<Details header="With a `--binding`">
```sh
npx wrangler kv key get --binding=<BINDING_NAME> "<KEY>"
```
</Details>
<Details header ="With a `--namespace-id`">
```sh
npx wrangler kv key get --namespace-id=<YOUR_ID> "<KEY>"
```
</Details>
</Steps>
You can add a `--preview` flag to interact with a preview namespace instead of a production namespace.
:::caution
Exactly **one** of `--binding` or `--namespace-id` is required.
:::
:::note
To view the value directly within the terminal, add `--text`
:::
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:
```ts
interface Env {
BINDING_NAME: KVNamespace;
// ... other binding types
}
```
2. Use the `put()` method on `BINDING_NAME` to create a new key-value pair, or to update the value for a particular key:
```ts
let value = await env.BINDING_NAME.put(key, value);
```
3. Use the KV `get()` method to fetch the data you stored in your KV database:
```ts
let value = await env.BINDING_NAME.get("KEY");
```
</Steps>
Your Worker code should look like this:
```ts
export interface Env {
BINDING_NAME: KVNamespace;
}
export default {
async fetch(request, env, ctx): Promise<Response> {
try {
await env.BINDING_NAME.put("KEY", "VALUE");
const value = await env.BINDING_NAME.get("KEY");
if (value === null) {
return new Response("Value not found", { status: 404 });
}
return new Response(value);
} catch (err) {
// In a production application, you could instead choose to retry your KV
// read or fall back to a default code path.
console.error(`KV returned error: ${err}`);
return new Response(err, { status: 500 });
}
},
} satisfies ExportedHandler<Env>;
```
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.
To run your project locally, enter the following command within your project directory:
```sh
npx wrangler dev
```
When you run `wrangler dev`, Wrangler provides a URL (usually a `localhost:8787`) to review your Worker. The browser prints your value when you visit the URL provided by Wrangler.
The browser should simply return the `VALUE` corresponding to the `KEY` you have specified with the `get()` method.
</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.
```js
export default {
async fetch(request, env, ctx) {
try {
await env.BINDING_NAME.put("KEY", "VALUE");
const value = await env.BINDING_NAME.get("KEY");
if (value === null) {
return new Response("Value not found", { status: 404 });
}
return new Response(value);
} catch (err) {
// In a production application, you could instead choose to retry your KV
// read or fall back to a default code path.
console.error(`KV returned error: ${err}`);
return new Response(err.toString(), { status: 500 });
}
},
};
```
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 KV
<Tabs syncKey = 'CLIvsDash'><TabItem label = 'CLI'>
<Steps>
1. Run the following command to deploy KV to Cloudflare's global network:
```sh
npx wrangler 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": "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/subresources/namespaces/methods/list/) 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">
 Learn about KV limits.
</LinkTitleCard>
<LinkTitleCard title="Pricing" href="/kv/platform/pricing/" icon="seti:shell">
 Learn about KV pricing.
</LinkTitleCard>
<LinkTitleCard
title="Discord"
href="https://discord.com/channels/595317990191398933/893253103695065128"
icon="discord"
>
 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">
 Learn about product announcements, new tutorials, and what is new in
Cloudflare Developer Platform.
</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/
```
---
# Overview
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>
---
# 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.
---
# Get started
URL: https://developers.cloudflare.com/pub-sub/guide/
import { Render } 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/setup/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:
<Render file="install_wrangler" product="workers" />
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
---
# Overview
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.
---
# 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"]} />
---
# Overview
URL: https://developers.cloudflare.com/pages/
import { CardGrid, Description, Feature, LinkTitleCard, Plan, RelatedProduct, Render } 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="Migration guides" href="/pages/migrations/" icon="pen">
Migrate to Pages from your existing hosting provider.
</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>
---
# 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"]} />
---
# Get 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: "Hello World Worker",
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" />
---
# Overview
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"]} />
---
# Get started
URL: https://developers.cloudflare.com/r2/get-started/
import { Render } 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.
<Render file="install_wrangler" product="workers" />
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:
* [Workers Runtime API](/r2/api/workers/workers-api-usage/)
* [S3 API compatibility](/r2/api/s3/api/)
* [Public buckets](/r2/buckets/public-buckets/)
---
# Overview
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/s3/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">
 Understand pricing for free and paid tier rates.
</LinkTitleCard>
<LinkTitleCard title="Discord" href="https://discord.cloudflare.com" icon="discord">
 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">
 Learn about product announcements, new tutorials, and what is new in Cloudflare Workers.
</LinkTitleCard>
</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 |
## 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](/support/account-management-billing/billing-cloudflare-plans/cloudflare-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.
---
# 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) or 413 (Payload too large) 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 (e.g. 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/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).
---
# Get started
URL: https://developers.cloudflare.com/stream/get-started/
:::note[Before you get started:]
You must first [create a Cloudflare account](/fundamentals/setup/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/).
---
# Overview
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">
 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
- Minutes of video delivered
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 minutes of video delivered, not per viewer.
**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 provided [WHIP example code](https://github.com/cloudflare/workers-sdk/blob/main/templates/stream/webrtc/src/whip.html#L13).
```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"; // an example WHIP client, see https://github.com/cloudflare/workers-sdk/blob/main/templates/stream/webrtc/src/WHIPClient.ts
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/id/draft-ietf-wish-whip-06.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 provided [WHEP example code](https://github.com/cloudflare/workers-sdk/blob/main/templates/stream/webrtc/src/whep.html#L13).
```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"; // an example WHEP client, see https://github.com/cloudflare/workers-sdk/blob/main/templates/stream/webrtc/src/WHEPClient.ts
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](https://github.com/cloudflare/workers-sdk/blob/main/templates/stream/webrtc/src/WHIPClient.ts) and [example WHEP client](https://github.com/cloudflare/workers-sdk/blob/main/templates/stream/webrtc/src/WHEPClient.ts) 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/id/draft-ietf-wish-whip-06.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.
---
# 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"]} />
---
# Overview
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>
***
## 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>
---
# Overview
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>
---
# 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 />
---
# Demos and architectures
URL: https://developers.cloudflare.com/workers-ai/demos/
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"]} />
---
# Glossary
URL: https://developers.cloudflare.com/workers-ai/glossary/
import { Glossary } from "~/components";
Review the definitions for terms used across Cloudflare's Workers AI documentation.
<Glossary product="workers-ai" />
---
# Overview
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>
---
# Privacy
URL: https://developers.cloudflare.com/workers-ai/privacy/
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.
---
# Errors
URL: https://developers.cloudflare.com/workers-ai/workers-ai-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/glossary/
import { Glossary } from "~/components";
Review the definitions for terms used across Cloudflare's Workers documentation.
<Glossary product="workers" />
---
# 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"]} />
---
# Overview
URL: https://developers.cloudflare.com/workers/
import {
CardGrid,
Description,
Feature,
LinkButton,
LinkTitleCard,
Plan,
RelatedProduct,
Render,
} from "~/components";
<Description>
Build serverless applications and deploy instantly across the globe for exceptional performance, reliability, and scale.
</Description>
<Plan type="all" />
Cloudflare Workers provides a [serverless](https://www.cloudflare.com/learning/serverless/what-is-serverless/) execution environment that allows you to create new applications or augment existing ones without configuring or maintaining infrastructure.
Cloudflare Workers runs on [Cloudflare’s global network](https://www.cloudflare.com/network/) in hundreds of cities worldwide, offering both [Free and Paid plans](/workers/platform/pricing/).
<LinkButton variant="primary" href="/workers/get-started/guide/">
Get started
</LinkButton> <LinkButton
variant="secondary"
href="https://dash.cloudflare.com/?to=/:account/workers-and-pages/create"
>
Workers dashboard
</LinkButton>
---
## Features
<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/#deploy) your Workers projects.
</Feature>
<Feature header="Bindings" href="/workers/runtime-apis/bindings/">
Bindings allow your Workers to interact with resources on the Cloudflare developer platform, including [R2](/r2/), [KV](/kv/concepts/how-kv-works/), [Durable Objects](/durable-objects/), and [D1](/d1/).
</Feature>
<Feature header="Playground" href="/workers/playground/" cta="Use the Playground">
The Playground is a sandbox which gives you an instant way to preview and test a Worker directly in the browser against any site. No setup required.
</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" 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>
<RelatedProduct header="Queues" href="/queues/" product="queues">
Send and receive messages with guaranteed delivery and no charges for egress bandwidth.
</RelatedProduct>
<RelatedProduct header="Hyperdrive" href="/hyperdrive/" product="hyperdrive">
Turn your existing regional database into a globally distributed database.
</RelatedProduct>
<RelatedProduct header="Vectorize" href="/vectorize/" product="vectorize">
Build full-stack AI applications with Vectorize, Cloudflare’s vector database.
</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="Learning Path"
href="/learning-paths/workers/concepts/"
icon="pen"
>
New to Workers? Get started with the Workers Learning Path.
</LinkTitleCard>
<LinkTitleCard
title="Plans"
href="/workers/platform/pricing/"
icon="seti:shell"
>
Learn about Free and Paid plans.
</LinkTitleCard>
<LinkTitleCard title="Limits" href="/workers/platform/limits/" icon="document">
Learn about plan limits (Free plans get 100,000 requests per day).
</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>
---
# Local development
URL: https://developers.cloudflare.com/workers/local-development/
Cloudflare Workers and most connected resources can be fully developed and tested locally - providing confidence that the applications you build locally will work the same way in production. This allows you to be more efficient and effective by providing a faster feedback loop and removing the need to [test against remote resources](#develop-using-remote-resources-and-bindings). Local development runs against the same production runtime used by Cloudflare Workers, [workerd](https://github.com/cloudflare/workerd).
In addition to testing Workers locally with [`wrangler dev`](/workers/wrangler/commands/#dev), the use of Miniflare allows you to test other Developer Platform products locally, such as [R2](/r2/), [KV](/kv/), [D1](/d1/), and [Durable Objects](/durable-objects/).
## Start a local development server
:::note
This guide assumes you are using [Wrangler v3.0](https://blog.cloudflare.com/wrangler3/) or later.
Users new to Wrangler CLI and Cloudflare Workers should visit the [Wrangler Install/Update guide](/workers/wrangler/install-and-update) to install `wrangler`.
:::
Wrangler provides a [`dev`](/workers/wrangler/commands/#dev) command that starts a local server for developing your Worker. Make sure you have `npm` installed and run the following in the folder containing your Worker application:
```sh
npx wrangler dev
```
`wrangler dev` will run the Worker directly on your local machine. `wrangler dev` uses a combination of `workerd` and [Miniflare](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare), a simulator that allows you to test your Worker against additional resources like KV, Durable Objects, WebSockets, and more.
### Supported resource bindings in different environments
| Product | Local Dev Supported | Remote Dev Supported |
| ----------------------------------- | ------------------- | -------------------- |
| AI | ✅[^1] | ✅ |
| Assets | ✅ | ✅ |
| Analytics Engine | ✅ | ✅ |
| Browser Rendering | ⌠| ✅ |
| D1 | ✅ | ✅ |
| Durable Objects | ✅ | ✅ |
| Email Bindings | ⌠| ✅ |
| Hyperdrive | ✅ | ✅ |
| Images | ✅ | ✅ |
| KV | ✅ | ✅ |
| mTLS | ⌠| ✅ |
| Queues | ✅ | ⌠|
| R2 | ✅ | ✅ |
| Rate Limiting | ✅ | ✅ |
| Service Bindings (multiple workers) | ✅ | ✅ |
| Vectorize | ✅[^2] | ✅ |
| Workflows | ✅ | ⌠|
With any bindings that are not supported locally, you will need to use the [`--remote` command](#develop-using-remote-resources-and-bindings) in wrangler, such as `wrangler dev --remote`.
[^1]: Using Workers AI always accesses your Cloudflare account in order to run AI models and will incur usage charges even in local development.
[^2]: Using Vectorize always accesses your Cloudflare account to run queries, and will incur usage charges even in local development.
## Work with local data
When running `wrangler dev`, resources such as KV, Durable Objects, D1, and R2 will be stored and persisted locally and not affect the production resources.
### Use bindings in Wrangler configuration files
[Wrangler](/workers/wrangler/) will automatically create local versions of bindings found in the [Wrangler configuration file](/workers/wrangler/configuration/). These local resources will not have data in them initially, so you will need to add data manually via Wrangler commands and the [`--local` flag](#use---local-flag).
When you run `wrangler dev` Wrangler stores local resources in a `.wrangler/state` folder, which is automatically created.
If you prefer to specify a directory, you can use the [`--persist-to`](/workers/wrangler/commands/#dev) flag with `wrangler dev` like this:
```sh
npx wrangler dev --persist-to <DIRECTORY>
```
Using this will write all local storage and cache to the specified directory instead of `.wrangler`.
:::note
This local persistence folder should be added to your `.gitignore` file.
:::
### Use `--local` flag
The following [Wrangler commands](/workers/wrangler/commands/) have a `--local` flag which allows you to create, update, and delete local data during development:
| Command |
| ---------------------------------------------------- |
| [`d1 execute`](/workers/wrangler/commands/#execute) |
| [`kv key`](/workers/wrangler/commands/#kv-key) |
| [`kv bulk`](/workers/wrangler/commands/#kv-bulk) |
| [`r2 object`](/workers/wrangler/commands/#r2-object) |
If using `--persist-to` to specify a custom folder with `wrangler dev` you should also add `--persist-to` with the same directory name along with the `--local` flag when running the commands above. For example, to put a custom KV key into a local namespace via the CLI you would run:
```sh
npx wrangler kv key put test 12345 --binding MY_KV_NAMESPACE --local --persist-to worker-local
```
Running `wrangler kv key put` will create a new key `test` with a value of `12345` on the local namespace specified via the binding `MY_KV_NAMESPACE` in the [Wrangler configuration file](/workers/wrangler/configuration/). This example command sets the local persistence directory to `worker-local` using `--persist-to`, to ensure that the data is created in the correct location. If `--persist-to` was not set, it would create the data in the `.wrangler` folder.
### Clear Wrangler's local storage
If you need to clear local storage entirely, delete the `.wrangler/state` folder. You can also be more fine-grained and delete specific resource folders within `.wrangler/state`.
Any deleted folders will be created automatically the next time you run `wrangler dev`.
## Local-only environment variables
When running `wrangler dev`, variables in the [Wrangler configuration file](/workers/wrangler/configuration/) are automatically overridden by values defined in a `.dev.vars` file located in the root directory of your worker. This is useful for providing values you do not want to check in to source control.
```shell
API_HOST = "localhost:4000"
API_ACCOUNT_ID = "local_example_user"
```
## Develop using remote resources and bindings
There may be times you want to develop against remote resources and bindings. To run `wrangler dev` in remote mode, add the `--remote` flag, which will run both your code and resources remotely:
```sh
npx wrangler dev --remote
```
For some products like KV and R2, remote resources used for `wrangler dev --remote` must be specified with preview ID/names in the [Wrangler configuration file](/workers/wrangler/configuration/) such as `preview_id` for KV or `preview_bucket name` for R2. Resources used for remote mode (preview) can be different from resources used for production to prevent changing production data during development. To use production data in `wrangler dev --remote`, set the preview ID/name of the resource to the ID/name of your production resource.
## Customize `wrangler dev`
You can customize how `wrangler dev` works to fit your needs. Refer to [the `wrangler dev` documentation](/workers/wrangler/commands/#dev) for available configuration options.
:::caution
There is a bug associated with how outgoing requests are handled when using `wrangler dev --remote`. For more information, read the [Known issues section](/workers/platform/known-issues/#wrangler-dev).
:::
## Related resources
- [D1 local development](/d1/best-practices/local-development/) - The official D1 guide to local development and testing.
- [DevTools](/workers/observability/dev-tools) - Guides to using DevTools to debug your Worker locally.
---
# 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.
---
# 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 />
---
# 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`.
---
# 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.
---
# 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/setup/) 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 and website.
2. Select **Zaraz** from the side menu.
3. If you have already added a tool before, select **Tools Configuration** > **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.
---
# Overview
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>
---
# 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.
---
# API Reference
URL: https://developers.cloudflare.com/agents/api-reference/
import { DirectoryListing } from "~/components"
<DirectoryListing />
---
# 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.
The typical file structure for an Agent project created from `npm create cloudflare@latest -- --template cloudflare/agents` 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
```
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 SDK
URL: https://developers.cloudflare.com/agents/api-reference/sdk/
import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";
At its most basic, an Agent is a JavaScript 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.
<TypeScriptExample>
```ts
import { Agent } from "agents-sdk";
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.
## The Agent class
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.
An Agent has the following class methods:
<TypeScriptExample>
```ts
import { Agent } from "agents-sdk";
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>
class MyAgent extends Agent<Env> {
// Called when an Agent is started (or woken up)
async onStart() {
// Can access this.env and this.state
console.log('Agent started');
}
// Called when a HTTP request is received
// Can be connected to routeAgentRequest to automatically route
// requests to an individual Agent.
async onRequest(request: Request) {
console.log("Received request!");
}
// Called when a WebSocket connection is established
async onConnect(connection: Connection, ctx: ConnectionContext) {
console.log("Connected!");
// Check the request at ctx.request
// Authenticate the client
// Give them the OK.
connection.accept();
}
// Called for each message received on the WebSocket connection
async onMessage(connection: Connection, message: WSMessage) {
console.log(`message from client ID: ${connection.id}`)
// Send messages back to the client
connection.send("Hello!");
}
// 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();
}
// Called when the Agent's state is updated
// via this.setState or the useAgent hook from the agents-sdk/react package.
async onStateUpdate(state: any) {
// 'state' will be typed if you supply a type parameter to the Agent class.
}
}
export default MyAgent;
```
</TypeScriptExample>
:::note
To learn more about how to manage state within an Agent, refer to the documentation on [managing and syncing state](/agents/examples/manage-and-sync-state/).
:::
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`.
## Calling Agents from Workers
You can create and run an instance of an Agent directly from a Worker in one of three ways:
1. Using 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.
2. Calling `getAgentByName`, which will create a new Agent instance if none exists by that name, or retrieve a handle to an existing instance.
3. The [Durable Objects stub API](/durable-objects/api/id/), which provides a lower level API for creating and retrieving Agents.
These three patterns are shown below: we recommend using either `routeAgentRequest` or `getAgentByName`, which help avoid some boilerplate.
<TypeScriptExample>
```ts
import { Agent, AgentNamespace, getAgentByName, routeAgentRequest } from 'agents-sdk';
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-sdk/react
(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.
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);
// Durable Objects-style addressing
// Best for: controlling ID generation, associating IDs with your existing systems,
// and customizing when/how an Agent is created or invoked
const id = env.MyAgent.newUniqueId();
const agent = env.MyAgent.get(id);
// Pass the incoming request straight to your Agent
let resp = await agent.fetch(request);
return Response.json({ hello: 'visit https://developers.cloudflare.com/agents for more' });
},
} satisfies ExportedHandler<Env>;
export class MyAgent extends Agent<Env> {
// Your Agent implementation goes here
}
```
</TypeScriptExample>
---
# Browse the web
URL: https://developers.cloudflare.com/agents/examples/browse-the-web/
import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } 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:
```sh
npm install @cloudflare/puppeteer --save-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:
```sh
npm install @cloudflare/puppeteer
```
<TypeScriptExample>
```ts
interface Env {
BROWSERBASE_API_KEY: string;
}
export class MyAgent extends Agent<Env> {
constructor(env: Env) {
super(env);
}
}
```
</TypeScriptExample>
---
# Examples
URL: https://developers.cloudflare.com/agents/examples/
import { DirectoryListing, PackageManagers } from "~/components";
Agents running on Cloudflare can:
<DirectoryListing />
---
# Manage and sync state
URL: https://developers.cloudflare.com/agents/examples/manage-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 persisted within the 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
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) 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-sdk";
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-sdk";
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>
### Synchronizing state
Clients can connect to an Agent and stay synchronized with its state using the React hooks provided as part of `agents-sdk/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-sdk/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) 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 paramter 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/sql-storage/): 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/examples/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.
---
# Retrieval Augmented Generation
URL: https://developers.cloudflare.com/agents/examples/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/examples/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/examples/browse-the-web/) tasks to enhance your Agent's capabilities.
You can use the Agent's own [SQL database](/agents/examples/manage-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 capabilties:
<TypeScriptExample>
```ts
import { Agent } from "agents-sdk";
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
---
# Run Workflows
URL: https://developers.cloudflare.com/agents/examples/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 tthe 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/examples/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-sdk"
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/sql-storage/), 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>
---
# Using WebSockets
URL: https://developers.cloudflare.com/agents/examples/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-sdk";
export class ChatAgent extends Agent {
async onConnect(connection: Connection, ctx: ConnectionContext) {
// Access the request to verify any authentication tokens
// provided in headers or cookies
let token = ctx.request.headers.get("Authorization");
if (!token) {
await connection.close(4000, "Unauthorized");
return;
}
// Handle auth using your favorite library and/or auth scheme:
// try {
// await jwt.verify(token, env.JWT_SECRET);
// } catch (error) {
// connection.close(4000, 'Invalid Authorization header');
// return;
// }
// Accept valid connections
connection.accept()
}
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-sdk/client`, create an instance of `AgentClient` and use it to connect to an instance of your Agent:
<TypeScriptExample>
```ts
import { AgentClient } from "agents-sdk/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-sdk/react` and use the `useAgent` hook to connect to an instance of an Agent directly:
<TypeScriptExample>
```ts
import { useAgent } from "agents-sdk/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/examples/manage-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-sdk";
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>
---
# Using AI Models
URL: https://developers.cloudflare.com/agents/examples/using-ai-models/
import { AnchorHeading, MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";
Agents can communicate with AI models hosted on any provider, including [Workers AI](/workers-ai/), OpenAI, Anthropic, and Google's Gemini, and 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. Tradtional 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/sdk/) handler, when a [scheduled task](/agents/examples/schedule-tasks/) runs, when handling a WebSocket message in the [`onMessage`](/agents/examples/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 disconecting, you can stream the response back to the client by using the [WebSocket API](/agents/examples/websockets/).
<TypeScriptExample filename="src/index.ts">
```ts
import { Agent } from "agents-sdk"
import { OpenAI } from "openai"
export class MyAgent extends Agent<Env> {
async onConnect(connection: Connection, ctx: ConnectionContext) {
// Omitted for simplicity: authenticating the user
connection.accept()
}
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/examples/manage-and-sync-state/) by using the `this.setState` method. For example, if you run a [scheduled task](/agents/examples/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-sdk"
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-sdk"
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.
```sh
npm install ai @ai-sdk/openai
```
<TypeScriptExample filename="src/index.ts">
```ts
import { Agent } from "agents-sdk"
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/examples/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-sdk"
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>
---
# 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/
import { Render, Note, Aside } from "~/components";
### 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.
#### 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
#### 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
#### 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 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-sdk-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/get-started/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 />
---
# Reference
URL: https://developers.cloudflare.com/agents/platform/
import { DirectoryListing } from "~/components";
Build AI Agents on Cloudflare
<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 (e.g. 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/examples/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";
Enable and customize your gateway cache to serve requests directly from Cloudflare's cache, instead of the original model provider, for faster requests and cost savings.
:::note
Currently caching is supported only for text and image responses, and it applies only to identical requests.
This is helpful for use cases when there are 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/setup/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
In order to override the default cache behavior defined on the settings tab, you can, on a per-request basis, set headers for the following options:
:::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/providers/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](#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/providers/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 />
---
# 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" />
---
# 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'll encounter rate limiting. This means the server will respond with a `429 Too Many Requests` status code and your request won't 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/setup/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/providers/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/providers/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/providers/) 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)
---
# WebSockets API
URL: https://developers.cloudflare.com/ai-gateway/configuration/websockets-api/
The AI Gateway WebSockets API provides a single persistent connection, enabling continuous communication. By using WebSockets, you can establish a single connection for multiple AI requests, eliminating the need for repeated handshakes and TLS negotiations, which enhances performance and reduces latency. This API supports all AI providers connected to AI Gateway, including those that do not natively support WebSockets.
## When to use WebSockets?
WebSockets are long-lived TCP connections that enable bi-directional, real-time 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, we handle it for you, managing the requests to your preferred AI provider.
## 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"
}
}
```
---
# 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/setup/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 don't have the `cf-aig-log-id` in the response body or you need to access it after the fact, you can 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's 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/)
---
# 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.
---
# 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.
---
# 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.
:::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.
:::
---
# 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: "Hello World Worker",
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`,
});
```
### 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.
## Prerequisites
- Install and use the `@cloudflare/workers-types` library, version `4.20250124.3` or above.
## 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`.
## 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>`. You can import the `AiGatewayLog` type from the `@cloudflare/workers-types` library.
```typescript
const log = await gateway.getLog("my-log-id");
```
- **Returns**: `Promise<AiGatewayLog>`
- **Example Use Case**: Retrieve log information for debugging or analytics.
### 3.3. `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/providers/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/providers/universal/) to any supported provider.
## Conclusion
With the new AI Gateway binding methods, you can now:
- Send feedback and update metadata with `patchLog`.
- Retrieve detailed log information using `getLog`.
- 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/
## Supported Providers
AI Gateway currently supports cost metrics from the following providers:
- Anthropic
- Azure OpenAI
- Cohere
- Google AI Studio
- Groq
- Mistral
- OpenAI
- Perplexity
- Replicate
Cost metrics are only available for endpoints where the models return token data and the model name in their responses.
:::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 />
---
# Audit logs
URL: https://developers.cloudflare.com/ai-gateway/reference/audit-logs/
[Audit logs](/fundamentals/setup/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](https://developers.cloudflare.com/fundamentals/setup/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 />
---
# 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 (Beta)
:::note[Note]
Billing for persistent log storage will begin on April 15, 2025. Users on paid plans can store logs beyond the included volume of 200,000 logs stored a month without being charged until this date. Users on the free plan remain limited to the 100,000 logs cap for their plan. Please ensure your stored logs are within your plan's included volume before April 14, 2025, if you do not want to be charged.
:::
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).
## 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.
---
# Anthropic
URL: https://developers.cloudflare.com/ai-gateway/providers/anthropic/
[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,
});
```
---
# 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 | 10 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" />
---
# 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 requestData = {
inputText: "What does ethereal mean?",
};
const headers = {
"Content-Type": "application/json",
};
// sign the original request
const stockUrl = new URL(
"https://bedrock-runtime.us-east-1.amazonaws.com/model/amazon.titan-embed-text-v1/invoke",
);
const awsClient = new AwsClient({
accessKeyId: accessKey,
secretAccessKey: secretKey,
region: region,
service: "bedrock",
});
const presignedRequest = await awsClient.sign(stockUrl.toString(), {
method: "POST",
headers: headers,
});
// change the signed request's host to AI Gateway
const stockUrlSigned = new URL(presignedRequest.url);
stockUrlSigned.host = "gateway.ai.cloudflare.com";
stockUrlSigned.pathname = `/v1/${cfAccountId}/${gatewayName}/aws-bedrock/bedrock-runtime/${region}/model/amazon.titan-embed-text-v1/invoke`;
// make request
const response = await fetch(stockUrlSigned, {
method: "POST",
headers: presignedRequest.headers,
body: JSON.stringify(requestData),
});
if (
response.ok &&
response.headers.get("content-type")?.includes("application/json")
) {
const data = await response.json();
return new Response(JSON.stringify(data));
} else {
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/
[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?"
}
]
}'
```
---
# Cohere
URL: https://developers.cloudflare.com/ai-gateway/providers/cohere/
[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)
```
---
# DeepSeek
URL: https://developers.cloudflare.com/ai-gateway/providers/deepseek/
[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);
}
```
---
# 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/
[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?"]);
```
---
# Grok
URL: https://developers.cloudflare.com/ai-gateway/providers/grok/
[Grok](https://docs.x.ai/docs#getting-started) is s 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)
```
---
# Groq
URL: https://developers.cloudflare.com/ai-gateway/providers/groq/
[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": "mixtral-8x7b-32768"
}'
```
### 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 = "mixtral-8x7b-32768";
const chatCompletion = await groq.chat.completions.create({
messages,
model,
});
```
---
# 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);
```
---
# 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 />
---
# Mistral AI
URL: https://developers.cloudflare.com/ai-gateway/providers/mistral/
[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?",
},
],
});
```
---
# 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
```
## URL structure
When making requests to OpenAI, replace `https://api.openai.com/v1` in the URL you’re 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.
## Examples
### cURL
```bash title="Request"
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"
}
]
}
'
```
### Use OpenAI SDK with JavaScript
If you are using a library like openai-node, set the `baseURL` to your OpenAI endpoint like this:
```js title="JavaScript"
import OpenAI from "openai";
const apiKey = "my api key"; // defaults to 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;
return new Response(JSON.stringify(response));
} catch (e) {
return new Response(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/
[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,
});
```
---
# 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?"
}
}'
```
---
# Universal Endpoint
URL: https://developers.cloudflare.com/ai-gateway/providers/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/configuration/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());
});
```
## 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?"
}
]
}
}
]'
```
---
# 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).
---
# 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 } from "~/components";
View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with AI Gateway.
<ListTutorials />
---
# 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: "Hello World Worker",
lang: "JavaScript",
}}
/>
Go to your new open Worker project:
```sh title="Open your new project directory"
cd openai-aig
```
Inside of your new opeai-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`:
```sh title="Install the OpenAI node library"
npm install 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:
```sh title="Save your API key to your Workers env"
npx wrangler 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:
```sh title="Deploy your Worker"
npx wrangler 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.
---
# 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>
---
# 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 5120 bytes.
* 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.
---
# 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.
---
# 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.
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.
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:
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:
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:
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
```
---
# 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 |
---
# 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>`;
}
```
---
# 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 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/).
---
# How To
URL: https://developers.cloudflare.com/browser-rendering/how-to/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# Generate PDFs Using HTML and CSS
URL: https://developers.cloudflare.com/browser-rendering/how-to/pdf-generation/
import { Aside, WranglerConfig } from "~/components";
As seen in the [Getting Started guide](/browser-rendering/workers-binding-api/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:
```sh
npm create cloudflare@latest -- browser-worker
```
2. Install `@cloudflare/puppeteer`, which allows you to control the Browser Rendering instance:
```sh
npm install @cloudflare/puppeteer --save-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're 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 });
return new Response(pdf, {
headers: {
"content-type": "application/pdf",
},
});
},
};
```
You can run this script to test it using Wrangler’s `--remote` flag:
```sh
npx wrangler@latest 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:
.
---
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. |
---
# Limits
URL: https://developers.cloudflare.com/browser-rendering/platform/limits/
import { Render, Plan } from "~/components";
<Plan type="workers-paid" />
## Workers Binding API
| Feature | Limit |
| -------------------------------- | ------------------- |
| Concurrent browsers per account | 10 per account [^1] |
| New browser instances per minute | 10 per minute [^1] |
| Browser timeout | 60 seconds [^1][^2] |
## REST API
| Feature | Limit |
| -------------------------------- | ------------------- |
| Concurrent browsers per account | 10 per account [^1] |
| New browser instances per minute | 10 per minute [^1] |
| Browser timeout | 60 seconds [^1][^2] |
| Total requests per minute | 60 per minute [^1] |
[^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.
---
# Puppeteer
URL: https://developers.cloudflare.com/browser-rendering/platform/puppeteer/
import { TabItem, Tabs } 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):
```bash
npm install @cloudflare/puppeteer --save-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-binding-api/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).
---
# Platform
URL: https://developers.cloudflare.com/browser-rendering/platform/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# 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).
---
# Deploy a Browser Rendering Worker with Durable Objects
URL: https://developers.cloudflare.com/browser-rendering/workers-binding-api/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. Enable Durable Objects in the dashboard
To enable Durable Objects, you will need to purchase the Workers Paid plan:
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account.
2. Go to **Workers & Pages** > **Plans**.
3. Select **Purchase Workers Paid** and complete the payment process to enable Durable Objects.
## 3. Install Puppeteer
In your `browser-worker` directory, install Cloudflare’s [fork of Puppeteer](/browser-rendering/platform/puppeteer/):
```sh
npm install @cloudflare/puppeteer --save-dev
```
## 4. 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.
## 5. 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_classes = ["Browser"] # Array of new classes
```
</WranglerConfig>
## 6. 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({ path: fileName + ".jpg" });
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();
}
}
}
}
```
## 7. 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.
## 8. 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/)
---
# Workers Binding API
URL: https://developers.cloudflare.com/browser-rendering/workers-binding-api/
import { DirectoryListing } from "~/components";
The Workers Binding API allows you to execute advanced browser rendering scripts within Cloudflare Workers. It provides developers the flexibility to automate and control complex workflows and browser interactions. The following options are available for browser rendering tasks:
<DirectoryListing />
Use the Workers Binding API 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.
---
# Reuse sessions
URL: https://developers.cloudflare.com/browser-rendering/workers-binding-api/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-binding-api/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: "Hello World Worker",
lang: "TypeScript",
}}
/>
## 2. Install Puppeteer
In your `browser-worker` directory, install Cloudflare's [fork of Puppeteer](/browser-rendering/platform/puppeteer/):
```sh
npm install @cloudflare/puppeteer --save-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!)
await 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've 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`
---
# Deploy a Browser Rendering Worker
URL: https://developers.cloudflare.com/browser-rendering/workers-binding-api/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: "Hello World Worker",
lang: "JavaScript / TypeScript",
}}
/>
## 2. Install Puppeteer
In your `browser-worker` directory, install Cloudflare’s [fork of Puppeteer](/browser-rendering/platform/puppeteer/):
```sh
npm install @cloudflare/puppeteer --save-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)
---
# Fetch HTML
URL: https://developers.cloudflare.com/browser-rendering/rest-api/content-endpoint/
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
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"}'
```
## 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/screenshot/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, the [Workers Binding API](/browser-rendering/workers-binding-api/) is 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`
---
# Render PDF
URL: https://developers.cloudflare.com/browser-rendering/rest-api/pdf-endpoint/
The `/pdf` endpoint instructs the browser to render the webpage as a PDF document.
## Basic usage
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"
```
## Advanced usage
Navigate to `https://example.com`, first setting an additional HTTP request header and configuring the page size (`viewport`). Then, wait until there are no more than 2 network connections for at least 500 ms, or until the maximum timeout of 4500 ms is reached, before considering the page loaded and returning the rendered PDF document.
The `goToOptions` parameter exposes most of [Puppeteer'd 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. 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"
```
## Generate PDF from custom HTML
If you have HTML you'd like to generate a PDF from, the `html` option can be used. The option `addStyleTag` can be used to add custom styles.
```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"
```
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/pdf/methods/create/) for all available parameters.
---
# Scrape HTML elements
URL: https://developers.cloudflare.com/browser-rendering/rest-api/scrape-endpoint/
The `/scrape` endpoint extracts structured data from specific elements on a webpage, returning details such as element dimensions and inner HTML.
## Basic usage
Go to `https://example.com` and 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 response
```json title="json response"
{
"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"
}
]
}
```
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.
---
# Capture screenshot
URL: https://developers.cloudflare.com/browser-rendering/rest-api/screenshot-endpoint/
The `/screenshot` endpoint renders the webpage by processing its HTML and JavaScript, then captures a screenshot of the fully rendered page.
## Basic usage
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"
```
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.
---
# Take a webpage snapshot
URL: https://developers.cloudflare.com/browser-rendering/rest-api/snapshot/
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
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 response
```json title="json response"
{
"success": true,
"result": {
"screenshot": "Base64EncodedScreenshotString",
"content": "<html>...</html>"
}
}
```
## 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 response
```json title="json response"
{
"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/screenshot/methods/create/) for all available parameters.
---
# Analytics
URL: https://developers.cloudflare.com/calls/turn/analytics/
Cloudflare Calls 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 Calls 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](/calls/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/calls/turn/custom-domains/
Cloudflare Calls 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 Calls 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 Calls TURN.
---
# FAQ
URL: https://developers.cloudflare.com/calls/turn/faq/
## General
### What is Cloudflare Calls 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 Calls 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 Calls billing appears as a single line item on your Cloudflare bill, covering both SFU and TURN.
Traffic between Cloudflare Calls TURN and Cloudflare Calls SFU or Cloudflare Stream (WHIP/WHEP) does not incur any charges.
<div class="full-img">
```mermaid
---
title: Cloudflare Calls 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 Calls 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 Calls 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 Calls TURN operate at?
Cloudflare Calls 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 Calls TURN use the Cloudflare Backbone or is there any "magic" Cloudflare do to speed connection up?
Cloudflare Calls 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 Calls 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 Calls TURN with a enterprise plan vs self-serve (pay with your credit card) plans?
There is no performance or feature level difference for Cloudflare Calls 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 Calls TURN run in the Cloudflare China Network?
Cloudflare's [China Network](/china-network/) does not participate in serving Calls 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 Calls TURN IP addresses. Which IP addresses should I use?
Cloudflare Calls 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 Calls TURN support the expired IETF RFC draft "draft-uberti-behave-turn-rest-00"?
The Cloudflare Calls 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 Calls credential generation endpoint to the required format in your backend server or Cloudflare Workers.
### I am observing packet loss when using Cloudflare Calls 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? Calls 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 Calls 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 Calls 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 Calls TURN support IPv6?
Yes. Cloudflare Calls 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 Calls TURN issue IPv6 relay addresses?
No. Calls TURN will not respect `REQUESTED-ADDRESS-FAMILY` STUN attribute if specified and will issue IPv4 addresses only.
### Does Calls TURN support TCP relaying?
No. Calls 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 Calls 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 Calls TURN, please reach out to your account manager for further details.
### What will happen if TURN credentials expire while the TURN allocation is in use?
Cloudflare Calls 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/calls/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"
}
]
}
```
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/calls/turn/
Separately from the SFU, Calls 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 Calls TURN service is available free of charge when used together with the Calls 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 reccomended. 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
Calls 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 Calls](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 Calls TURN service.
## Limits
Cloudflare Calls 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/calls/turn/replacing-existing/
If you are a existing TURN provider but would like to switch to providing Cloudflare Calls TURN for your customers, there is a few considerations.
## Benefits
Cloudflare Calls 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 Calls 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 Calls 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](/calls/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](/calls/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 Calls 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/calls/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](/calls/turn/faq/#does-cloudflare-calls-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/calls/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 Calls 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.
---
# 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.
### 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/).
### 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.
## 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>
---
# 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" />
---
# Demos
URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/demos/
import { ExternalResources, GlossaryTooltip } 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"]} />
---
# 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>
---
# 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 />
---
# 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.
## 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 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 │
└────────────┴─────────────────────┴───────────────────┘
```
---
# 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.
---
# 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"
}
]
}
}
}
```
---
# 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 database 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 database.
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.
:::
---
# Configuration
URL: https://developers.cloudflare.com/d1/configuration/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# 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>
---
# 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>
---
# 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 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 js 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.
---
# 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/" />
---
# Audit Logs
URL: https://developers.cloudflare.com/d1/observability/audit-logs/
[Audit logs](/fundamentals/setup/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/setup/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"
}
```
---
# 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
---
# 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/local-development/).
---
# 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
query {
viewer {
accounts(filter: { accountTag: $accountId }) {
d1AnalyticsAdaptiveGroups(
limit: 10000
filter: {
date_geq: $startDate
date_leq: $endDate
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
query {
viewer {
accounts(filter: { accountTag: $accountId }) {
d1AnalyticsAdaptiveGroups(
limit: 10000
filter: {
date_geq: $startDate
date_leq: $endDate
databaseId: $databaseId
}
orderBy: [date_DESC]
) {
quantiles {
queryBatchTimeMsP90
}
dimensions {
date
databaseId
}
}
}
}
}
```
To query your account-wide `readQueries` and `writeQueries`:
```graphql
query {
viewer {
accounts(filter: { accountTag: $accountId }) {
d1AnalyticsAdaptiveGroups(
limit: 10000
filter: {
date_geq: $startDate
date_leq: $endDate
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.
:::
---
# Changelog
URL: https://developers.cloudflare.com/d1/platform/changelog/
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 />
---
# Platform
URL: https://developers.cloudflare.com/d1/platform/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# Limits
URL: https://developers.cloudflare.com/d1/platform/limits/
import { Render } 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)) | 50 (Bundled) / 1000 (Unbound) |
| 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 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).
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.
:::
---
# 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.
---
# 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/changelog/#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/changelog/#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>
```
---
# Backups (Legacy)
URL: https://developers.cloudflare.com/d1/reference/backups/
D1 has built-in support for creating and restoring backups of your databases, including support for scheduled automatic backups and manual backup management.
:::caution[Time Travel]
The snapshot based backups described in this documentation are deprecated, and limited to the original alpha databases.
Databases using D1's [production 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.
:::
## 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" />
---
# Reference
URL: https://developers.cloudflare.com/d1/reference/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# 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.
## 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.
---
# Time Travel and backups
URL: https://developers.cloudflare.com/d1/reference/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.
- 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 introduces the concept of a "bookmark" to D1. A bookmark represents the state of a database at a specific point in time, and is effectively an append-only log.
- Bookmarks are lexicographically sortable. Sorting orders a list of bookmarks from oldest-to-newest.
- 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 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).
## 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.
---
# 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 = on` 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.
---
# SQL API
URL: https://developers.cloudflare.com/d1/sql-api/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# 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.
<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 } from "~/components"
View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with D1.
<ListTutorials />
---
# 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.
---
# 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/worker-api/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 [`@cloudflare/workers-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. The type conversion is as follows:
| JavaScript | D1 |
| -------------------- | ---------------------------------------------------------------------------- |
| null | `NULL` |
| Number | `REAL` |
| Number <sup>1</sup> | `INTEGER` |
| String | `TEXT` |
| Boolean <sup>2</sup> | `INTEGER` |
| ArrayBuffer | `BLOB` |
| undefined | Not supported. Queries with `undefined` values will return a `D1_TYPE_ERROR` |
<sup>1</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>2</sup> Booleans will be cast to an `INTEGER` type where `1` is `TRUE` and
`0` is `FALSE`.
## 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 = ?`);
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);
}
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 dev`.
```sh
npx wrangler dev
```
```sh output
â›…ï¸ wrangler 3.85.0 (update available 3.86.1)
-------------------------------------------------------
Your worker has access to the following bindings:
- D1 Databases:
- DB: <DATABASE_NAME> (DATABASE_ID) (local)
⎔ 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 │
╰───────────────────────────╯
```
3. Open a browser at the specified address.
</Steps>
### 4. Test the APIs
Change the URL to test the various D1 Worker Binding APIs.
---
# 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.
---
# 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
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)
```
```js
{
"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"
}
]
}
```
## `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
}
```
---
# 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.
<Tabs> <TabItem label="pnpm">
```sh
pnpm install @sanity/client
```
</TabItem> <TabItem label="npm">
```sh
npm install @sanity/client
```
</TabItem> <TabItem label="yarn">
```sh
yarn add @sanity/client
```
</TabItem> </Tabs>
## 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.
---
# 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.
---
# 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: "Hello World Worker",
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/)
---
# 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/frameworks/framework-guides/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 --experimental"}
/>
<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/cloudflare) that will run in a Worker using [Workers Static Assets](/workers/frameworks/framework-guides/nextjs/#static-assets).
Before we get started, open your project's `tsconfig.json` file and add 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
```
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 the newly generated `env.d.ts` file and add the following to the <Type text="CloudflareEnv" /> interface:
```ts title="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 `env.d.ts`, add your D1 binding, like:
```ts title="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 `env.d.ts` should now include the following:
```ts title="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()).env.AUTH_RESEND_KEY,
from: (await getCloudflareContext()).env.AUTH_EMAIL_FROM,
}),
],
adapter: D1Adapter((await getCloudflareContext()).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 to persist session data containing the following:
<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 type { NextRequest } from 'next/server';
import { up } from "@auth/d1-adapter";
import { getCloudflareContext } from "@opennextjs/cloudflare";
export async function GET(request: NextRequest) {
try {
await up((await getCloudflareContext()).env.DB)
} catch (e: any) {
console.log(e.cause.message, 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
- 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()).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.
:::
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.
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.
### `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.
- 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. 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 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 />
---
# SQL Storage
URL: https://developers.cloudflare.com/durable-objects/api/sql-storage/
import { Render, Type, MetaInfo, GlossaryTooltip } from "~/components";
The `SqlStorage` interface encapsulates methods that modify the SQLite database embedded within a Durable Object. The `SqlStorage` interface is accessible via the `sql` property 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');`
);
}
}
```
:::note[SQLite in Durable Objects Beta]
SQL API methods accessed with `ctx.storage.sql` are only allowed on [Durable Object classes with SQLite storage backend](/durable-objects/reference/durable-objects-migrations/#enable-sqlite-storage-backend-on-new-durable-object-class-migration) and will return an error if called on Durable Object classes with a key-value storage backend.
:::
:::note[Writing to indexes or virtual tables]
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.
:::
Specifically for Durable Object classes with SQLite storage backend, KV operations which were previously asynchronous (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.
## Methods
### `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()`, `toArray()`, and `one()` 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` had 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).
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;
```
## Point in time recovery
For [Durable Objects classes with SQL storage](/durable-objects/reference/durable-objects-migrations/#enable-sqlite-storage-backend-on-new-durable-object-class-migration), 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 times 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);
```
## 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 the "pointy 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.
---
# 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 Storage
URL: https://developers.cloudflare.com/durable-objects/api/storage-api/
import {
Render,
Type,
MetaInfo,
GlossaryTooltip,
TypeScriptExample,
} 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.
:::note[Scope of Durable Object storage]
Note that Durable Object storage is scoped by individual <GlossaryTooltip term="Durable Object">Durable Objects</GlossaryTooltip>.
- An account can have many Durable Object <GlossaryTooltip term="namespace">namespaces</GlossaryTooltip>.
- A namespace can have many Durable Objects.
However, storage is scoped per individual Durable Object.
:::
Durable Objects gain access to a persistent Durable Object Storage API via the `DurableObjectStorage` interface and accessed by the `DurableObjectState::storage` property. This is frequently accessed via `this.ctx.storage` when the `ctx` parameter passed to the Durable Object constructor.
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.
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>
## Methods
:::note[SQLite in Durable Objects Beta]
The new beta version of Durable Objects is available where each Durable Object has a private, embedded SQLite database. When deploying a new Durable Object class, users can [opt-in to a SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend) to access the new [SQL API](/durable-objects/api/sql-storage/#exec). Otherwise, a Durable Object class has a key-value storage backend.
:::
The Durable Object Storage API comes with several methods, including key-value (KV) API, SQL API, and point-in-time-recovery (PITR) API.
- Durable Object classes with the default, key-value storage backend can use KV API.
- Durable Object classes with the [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend) can use KV API, SQL API, and PITR API. KV API methods like `get()`, `put()`, `delete()`, or `list()` store data in a hidden SQLite table.
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.
### `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. Keys are limited to a max size of 2,048 bytes and values are limited to 128 KiB (131,072 bytes).<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. Each key is limited to a maximum size of 2,048 bytes and each value is limited to 128 KiB (131,072 bytes).
### `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.
### `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/#sqlite-storage-backend), `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.
#### 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.
### `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/sql-storage/#exec), will be considered part of the transaction.
### `transactionSync`
- `transactionSync(callback)`: <Type text='any' />
- Only available when using [the SQLite-backed storage engine](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend).
- 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/sql-storage/#exec), which complete sychronously.
### `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.
### `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`.
## Properties
### `sql`
`sql` is a readonly property of type `DurableObjectStorage` encapsulating the [SQL API](/durable-objects/api/sql-storage/).
## Related resources
- [Durable Objects: Easy, Fast, Correct – Choose Three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/)
- [WebSockets API](/durable-objects/best-practices/websockets/)
```
---
# 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.
```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 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
By default, a <GlossaryTooltip term="Durable Object class">Durable Object class</GlossaryTooltip> leverages a key-value storage backend. New Durable Object classes can opt-in to using a [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend).
[Storage API methods](/durable-objects/api/storage-api/#methods) are available on `ctx.storage` parameter passed to the Durable Object constructor. Storage API has key-value APIs and SQL APIs. Only Durable Object classes with a SQLite storage backend can access SQL API.
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;
}
}
```
### Removing 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. 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.
## SQLite storage backend
:::note[SQLite in Durable Objects Beta]
The new beta version of Durable Objects is available where each Durable Object has a private, embedded SQLite database. When deploying a new Durable Object class, users can opt-in to a SQLite storage backend in order to access new [SQL API](/durable-objects/api/sql-storage/#exec). Otherwise, a Durable Object class has a key-value storage backend.
:::
To allow a new Durable Object class to use SQLite storage backend, 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/sql-storage/#exec) is available on `ctx.storage.sql` parameter passed to the Durable Object constructor.
### Examples
<Render file="durable-objects-sql" />
<Render file="durable-objects-vs-d1" />
## Index for SQLite Durable Objects
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.
## Related resources
* [Zero-latency SQLite storage in every Durable Object blog post](https://blog.cloudflare.com/sqlite-in-durable-objects)
---
# Invoking 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 />
---
# Using WebSockets
URL: https://developers.cloudflare.com/durable-objects/best-practices/websockets/
import { Tabs, TabItem, GlossaryTooltip, Type } from "~/components";
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.
This guide covers:
1. Building a WebSocket server using Web Standard APIs
2. Using WebSocket Hibernation APIs.
## 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/tutorial/#5-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_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.
:::
## 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/tutorial/#5-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_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.
## 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/tutorial/#5-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"
[[durable_objects.bindings]]
name = "BATCHER"
class_name = "Batcher"
[[migrations]]
tag = "v1"
new_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/tutorial/#5-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"
[[durable_objects.bindings]]
name = "COUNTERS"
class_name = "Counter"
[[migrations]]
tag = "v1"
new_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/tutorial/#5-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"
[[durable_objects.bindings]]
name = "RATE_LIMITER"
class_name = "RateLimiter"
[[migrations]]
tag = "v1"
new_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/tutorial/#5-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"
[[durable_objects.bindings]]
name = "LOCATION"
class_name = "Location"
[[migrations]]
tag = "v1"
new_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.
<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);
this.ctx.blockConcurrencyWhile(async () => {
await this.ctx.storage.setAlarm(Date.now() + this.timeToLiveMs);
});
}
async fetch(_request) {
// Increment the TTL immediately following every 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);
this.ctx.blockConcurrencyWhile(async () => {
await this.ctx.storage.setAlarm(Date.now() + this.timeToLiveMs);
});
}
async fetch(_request: Request) {
// Increment the TTL immediately following every 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/tutorial/#5-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"
[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "MyDurableObject"
[[migrations]]
tag = "v1"
new_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 />
---
# 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).
---
# 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"
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/tutorial/#5-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"
[[durable_objects.bindings]]
name = "WEBSOCKET_HIBERNATION_SERVER"
class_name = "WebSocketHibernationServer"
[[migrations]]
tag = "v1"
new_classes = ["WebSocketHibernationServer"]
```
</WranglerConfig>
### Related resources
* [Durable Objects: Edge Chat Demo with Hibernation](https://github.com/cloudflare/workers-chat-demo/).
---
# 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/tutorial/#5-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"
[[durable_objects.bindings]]
name = "WEBSOCKET_SERVER"
class_name = "WebSocketServer"
[[migrations]]
tag = "v1"
new_classes = ["WebSocketServer"]
```
</WranglerConfig>
### Related resources
* [Durable Objects: Edge Chat Demo](https://github.com/cloudflare/workers-chat-demo).
---
# Get started
URL: https://developers.cloudflare.com/durable-objects/get-started/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# Tutorial with SQL API
URL: https://developers.cloudflare.com/durable-objects/get-started/tutorial-with-sql-api/
import { Render, TabItem, Tabs, PackageManagers, WranglerConfig } 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/).
:::note[SQLite in Durable Objects Beta]
The new beta version of Durable Objects is available where each Durable Object has a private, embedded SQLite database. When deploying a new Durable Object class, users can [opt-in to a SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend) in order to access new [SQL API](/durable-objects/api/sql-storage/#exec), part of Durable Objects Storage API.
:::
## Prerequisites
<Render file="prereqs" product="workers" />
## 1. Enable Durable Objects in the dashboard
To enable Durable Objects, you will need to purchase the Workers Paid plan:
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account.
2. Go to **Workers & Pages** > **Plans**.
3. Select **Purchase Workers Paid** and complete the payment process to enable Durable Objects.
## 2. Create a Worker project to access Durable Objects
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: "Hello World Worker Using 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
```
## 3. Write a class to define a Durable Object that uses 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> <TabItem label="JavaScript" icon="seti:javascript">
```js
export class MyDurableObject extends DurableObject {
constructor(ctx, env) {}
}
```
</TabItem> <TabItem label="TypeScript" icon="seti:typescript">
```ts
export class MyDurableObject extends DurableObject {
constructor(ctx: DurableObjectState, env: Env) {
// Required, as we're extending the base class.
super(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> <TabItem label="JavaScript" icon="seti:javascript">
```js
export class MyDurableObject extends DurableObject {
constructor(ctx: DurableObjectState, env: Env) {}
async sayHello() {
let result = this.ctx.storage.sql
.exec("SELECT 'Hello, World!' as greeting")
.one();
return result.greeting;
}
}
```
</TabItem> <TabItem label="TypeScript" icon="seti:typescript">
```ts
export class MyDurableObject extends DurableObject {
constructor(ctx: DurableObjectState, env: Env) {
// Required, as we're extending the base class.
super(ctx, env)
}
async sayHello() {
let result = this.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/sql-storage/#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.
## 4. 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> <TabItem label="JavaScript" icon="seti:javascript">
```js
export default {
async fetch(request, env) {
let id = env.MY_DURABLE_OBJECT.idFromName(new URL(request.url).pathname);
let stub = env.MY_DURABLE_OBJECT.get(id);
let greeting = await stub.sayHello();
return new Response(greeting);
},
};
```
</TabItem> <TabItem label="TypeScript" icon="seti:typescript">
```ts
export default {
async fetch(request, env, ctx): Promise<Response> {
let id = env.MY_DURABLE_OBJECT.idFromName(new URL(request.url).pathname);
let stub = env.MY_DURABLE_OBJECT.get(id);
let greeting = await stub.sayHello();
return new Response(greeting);
},
} satisfies ExportedHandler<Env>;
```
</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.
## 5. 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 `[[durable_objects.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.
## 6. 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.
## 7. 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.
## 8. 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`.
By finishing this tutorial, you have successfully created, tested and deployed a Durable Object.
### 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.
---
# Tutorial
URL: https://developers.cloudflare.com/durable-objects/get-started/tutorial/
import { Render, TabItem, Tabs, PackageManagers, WranglerConfig } from "~/components";
This guide will instruct you through:
- Writing a Durable Object class.
- Writing a Worker which invokes methods on a Durable Object.
- Deploying a Durable Object.
If you wish to learn more about Durable Objects, refer to [What are Durable Objects?](/durable-objects/what-are-durable-objects/).
## Prerequisites
<Render file="prereqs" product="workers" />
## 1. Enable Durable Objects in the dashboard
To enable Durable Objects, you will need to purchase the Workers Paid plan:
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account.
2. Go to **Workers & Pages** > **Plans**.
3. Select **Purchase Workers Paid** and complete the payment process to enable Durable Objects.
## 2. Create a Worker project
Durable Objects are accessed from a [Worker](/workers/).
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: "Hello World Worker using Durable Objects",
lang: "JavaScript / 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
```
## 3. Write a Durable Object class
Durable Objects are defined by a exporting a standard JavaScript class which extends from the `DurableObject` base 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, `state`, 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> <TabItem label="JavaScript" icon="seti:javascript">
```js
import { DurableObject } from "cloudflare:workers";
export class MyDurableObject extends DurableObject {
constructor(state, env) {}
}
```
</TabItem> <TabItem label="TypeScript" icon="seti:typescript">
```ts
import { DurableObject } from "cloudflare:workers";
export class MyDurableObject extends DurableObject {
constructor(state: DurableObjectState, env: Env) {}
}
```
</TabItem> </Tabs>
Workers can invoke public methods defined on a Durable Object via Remote Procedure Call (RPC).
The `sayHello` method demonstrates this capability:
<Tabs> <TabItem label="JavaScript" icon="seti:javascript">
```js
import { DurableObject } from "cloudflare:workers";
export class MyDurableObject extends DurableObject {
constructor(state, env) {}
async sayHello() {
return "Hello, World!";
}
}
```
</TabItem> <TabItem label="TypeScript" icon="seti:typescript">
```ts
import { DurableObject } from "cloudflare:workers";
export class MyDurableObject extends DurableObject {
constructor(state: DurableObjectState, env: Env) {}
async sayHello(): Promise<string> {
return "Hello, World!";
}
}
```
</TabItem> </Tabs>
## 4. Invoke methods on a Durable Object class
As mentioned previously, methods on a Durable Object class are invoked by a Worker. This is done by creating an ID refering to an instance of the Durable Object class, getting a stub that refers to a particular instance of a Durable Object class, and invoking methods on that stub.
The fetch handler should look like the following:
<Tabs> <TabItem label="JavaScript" icon="seti:javascript">
```js
// 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 rpcResponse = await stub.sayHello();
return new Response(rpcResponse);
},
};
```
</TabItem> <TabItem label="TypeScript" icon="seti:typescript">
```ts
// Worker
export default {
async fetch(request, env, ctx): Promise<Response> {
// 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 rpcResponse = await stub.sayHello();
return new Response(rpcResponse);
},
} satisfies ExportedHandler<Env>;
```
</TabItem> </Tabs>
## 5. Configure Durable Object bindings
To allow a Worker to invoke methods on a Durable Object, the Worker must have a [Durable Object binding](/workers/runtime-apis/bindings/) in the project's [Wrangler configuration file](/workers/wrangler/configuration/#durable-objects). The binding is configured to use a particular Durable Object class.
<WranglerConfig>
```toml
[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "MyDurableObject"
```
</WranglerConfig>
The `[[durable_objects.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. The name of the Worker if the Durable Object is external to this Worker.
- `environment` - Optional. The environment of the `script_name` to bind to.
Refer to [Wrangler Configuration](/workers/wrangler/configuration/#durable-objects) for more detail.
## 6. Configure Durable Object classes with migrations
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 will look like the following in your Worker's Wrangler file:
<WranglerConfig>
```toml
[[migrations]]
tag = "v1" # Should be unique for each entry
new_classes = ["MyDurableObject"] # Array of new classes
```
</WranglerConfig>
### 6.a Optional: Configure new Durable Object class for SQL storage
:::note[SQLite in Durable Objects Beta]
New beta version of Durable Objects is available where each Durable Object has a private, embedded SQLite database. SQL storage is opt-in during beta; otherwise, a Durable Object class has the standard, private key-value storage. Objects can access long-lived durable storage with the [Storage API](/durable-objects/api/storage-api/).
:::
A Durable Object class can only have a single storage type, which cannot be changed after the Durable Object class is created.
To configure SQL storage and API, replace `new_classes` with `new_sqlite_classes` 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.
## 7. 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.
## 8. 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`.
By finishing this tutorial, you have successfully created, tested and deployed a Durable Object.
### Related resources
- [Send requests to Durable Objects](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/)
- [Miniflare](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare) - Helpful tools for mocking and testing your Durable Objects.
---
# 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.
---
# Observability
URL: https://developers.cloudflare.com/durable-objects/observability/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# Platform
URL: https://developers.cloudflare.com/durable-objects/platform/
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.
---
# Limits
URL: https://developers.cloudflare.com/durable-objects/platform/limits/
import { Render, GlossaryTooltip } from "~/components";
Durable Objects are only available on the [Workers Paid plan](/workers/platform/pricing/#workers). Durable Objects limits are the same as [Workers Limits](/workers/platform/limits/), as well as the following limits that are specific to Durable Objects:
| Feature | Limit for class with key-value storage backend | Limit for class with SQLite storage backend [^1] |
| --------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------- |
| Number of Objects | Unlimited (within an account or of a given class) | Unlimited (within an account or of a given class) |
| Maximum Durable Object namespaces | 500 (identical to the [script limit](/workers/platform/limits/)) | 500 (identical to the [script limit](/workers/platform/limits/)) |
| Storage per account | 50 GB (can be raised by contacting Cloudflare) [^2] | 50 GB (can be raised by contacting Cloudflare) [^2] |
| Storage per class | Unlimited | Unlimited |
| Storage per Durable Object | Unlimited | 1 GB [^3] |
| Key size | 2 KiB (2048 bytes) | Key and value combined cannot exceed 2 MB |
| Value size | 128 KiB (131072 bytes) | Key and value combined cannot exceed 2 MB |
| WebSocket message size | 1 MiB (only for received messages) | 1 MiB (only for received messages) |
| CPU per request | 30s (including WebSocket messages) [^4] | 30s (including WebSocket messages) [^4] |
[^1]: The new beta version of Durable Objects is available where each Durable Object has a private, embedded SQLite database. When creating a Durable Object class, users can [opt-in to using SQL storage](/durable-objects/reference/durable-objects-migrations/#enable-sqlite-storage-backend-on-new-durable-object-class-migration).
[^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]: Will be raised to 10 GB for general availability.
[^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.
For Durable Object classes with [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend) 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 |
<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.
---
# Pricing
URL: https://developers.cloudflare.com/durable-objects/platform/pricing/
import { Render } from "~/components"
## Billing metrics
<Render file="durable_objects_pricing" product="workers" />
## Durable Objects 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).
## Storage API billing
<Render file="storage_api_pricing" product="workers" />
## 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 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 either by creating a [`DurableObjectNamespace`](/durable-objects/api/namespace/) restricted to a jurisdiction, or by creating an individual [`DurableObjectId`](/durable-objects/api/id) restricted to a jurisdiction:
```js
const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu");
const euId = euSubnamespace.newUniqueId();
// or
const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" });
```
Methods on a [`DurableObjectNamespace`](/durable-objects/api/namespace/) that take a [`DurableObjectId`](/durable-objects/api/id) as a parameter will throw an exception if the parameter is associated with a different jurisdiction. To achieve this, a [`DurableObjectId`](/durable-objects/api/id) encodes its jurisdiction. As a consequence, 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");
```
Methods on a [`DurableObjectNamespace`](/durable-objects/api/namespace/) that take a [`DurableObjectId`](/durable-objects/api/id) as a parameter will throw an exception if the parameter is associated with a different jurisdiction. However, these methods will not throw an exception if the [`DurableObjectNamespace`](/durable-objects/api/namespace/) is not associated with a jurisdiction. The common case is that any valid [`DurableObjectId`](/durable-objects/api/id) can be used in the top-level namespace's methods.
```js
const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu");
const euId = euSubnamespace.idFromName(name);
const stub = env.MY_DURABLE_OBJECT.get(euId);
```
### 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.
---
# 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/).
---
# Durable Objects migrations
URL: https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/
import { 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_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_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_classes = ["DurableObjectAClass"]
```
</WranglerConfig>
</Details>
## 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 new 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 top-level key in your `wrangler` configuration file. The migration list is inherited by all environments and cannot be overridden by a specific environment.
- 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.
:::
{/* ## Examples of Durable Object migration
To illustrate an example migrations workflow, the `DurableObjectExample` class can be initially defined with:
<WranglerConfig>
```toml
# Creating a new Durable Object class
[[migrations]]
tag = "v1" # Migration identifier. This should be unique for each migration entry
new_classes = ["DurableObjectExample"] # Array of new classes
```
</WranglerConfig>
You can rename the `DurableObjectExample` class to `UpdatedName` and delete an outdated `DeprecatedClass` entirely. You can create separate migrations for each operation, or combine them into a single migration as shown below. */}
## Enable SQLite storage backend on new Durable Object class migration
:::note[SQLite in Durable Objects Beta]
The new beta version of Durable Objects is available where each Durable Object has a private, embedded SQLite database. When deploying a new Durable Object class, users can opt-in to a SQLite storage backend in order to access new [SQL API](/durable-objects/api/sql-storage/#exec). Otherwise, a Durable Object class has a key-value storage backend.
:::
To allow a new Durable Object class to use a SQLite storage backend, use `new_sqlite_classes` on the migration in your Worker's `wrangler` configuration file:
<WranglerConfig>
```toml
[[migrations]]
tag = "v1" # Should be unique for each entry
new_sqlite_classes = ["MyDurableObject"] # Array of new classes
```
</WranglerConfig>
For an example of a new class migration, refer to [Get started: Configure Durable Object class with SQLite storage backend](/durable-objects/get-started/tutorial-with-sql-api/#6-configure-durable-object-class-with-sqlite-storage-backend).
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.
---
# Environments
URL: https://developers.cloudflare.com/durable-objects/reference/environments/
import { WranglerConfig } from "~/components";
[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>
---
# 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 />
---
# 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" />
---
# 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.
## Limits
If you encounter any allocation errors while using Email Workers, refer to [Limits](/email-routing/limits/#email-workers-size-limits) for more information.
---
# 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:
* 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 `In-Reply-To` header of the reply message must be set to the `Message-ID` of the incoming message.
* The recipient in the reply must match the incoming sender.
* The outgoing sender domain must match the same domain that received the email.
If these and other internal conditions are not met, then `reply()` will fail with an exception, otherwise you can freely compose your reply message and send it back to the original sender.
---
# 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: Service Worker
`EmailEvent` can be handled in Workers functions written using the Service Worker syntax by attaching to the `email` event with `addEventListener`:
```js
addEventListener("email", (event) => {
event.message.forward("<YOUR_EMAIL>");
});
```
### Properties
* `event.message` EmailMessage
* An [`EmailMessage` object](#emailmessage-definition).
***
## 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) {
message.forward("<YOUR_EMAIL>");
},
};
```
### Parameters
* `message` EmailMessage
* An [`EmailMessage` object](#emailmessage-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.
***
## `EmailMessage` definition
```ts
interface EmailMessage<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>;
}
```
* `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(messageEmailMessage)</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.
---
# 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!");
},
};
```
---
# 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/setup/account/account-security/review-audit-logs/) for more information.
---
# 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.
---
# 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.
:::
---
# 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 />
---
# 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**.
:::
---
# 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.
---
# 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.
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 press **Create Application**. Pick the "MTA-STS" template from the list.
5. This Worker proxies `https://mta-sts.mx.cloudflare.net/.well-known/mta-sts.txt` to your own domain. After deploying it, go to the Worker configuration, then **Triggers** > **Custom Domains** and **Add Custom Domain**. Type the subdomain `mta-sts.example.com`.
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/setup/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/).
---
# 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**.
---
# 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 />
---
# Connect to PostgreSQL
URL: https://developers.cloudflare.com/hyperdrive/configuration/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:
<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>
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 |
| ---------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Postgres.js (**recommended**) | [Postgres.js documentation](https://github.com/porsager/postgres) | `postgres@3.4.4` | Supported in both Workers & Pages. |
| node-postgres - `pg` | [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. |
| 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" />
## 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` | Not currently supported in beta | 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` | Not currently supported in beta | Identical to `verify-ca`, but also requires the database hostname must match a Subject Alternative Name (SAN) present on the certificate. |
:::caution
Hyperdrive does not currently support uploading client CA certificates. In the future, you will be able to provide the client CA to Hyperdrive as part of your database configuration.
:::
## 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.
### Postgres.js
The following Workers code shows you how to use [Postgres.js](https://github.com/porsager/postgres) with Hyperdrive.
<Render file="use-postgresjs-to-make-query" product="hyperdrive" />
### node-postgres / pg
Install the `node-postgres` driver:
```sh
npm install pg
```
**Ensure you have `compatibility_flags` and `compatibility_date` set in your [Wrangler configuration file](/workers/wrangler/configuration/)** as shown below:
<Render file="nodejs-compat-wrangler-toml" product="workers" />
Create a new `Client` instance and pass the Hyperdrive parameters:
```ts
import { Client } from "pg";
export interface Env {
// If you set another name in the Wrangler configuration 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> {
const client = new Client({
connectionString: env.HYPERDRIVE.connectionString,
});
try {
// Connect to your database
await client.connect();
// A very simple test query
const result = await client.query({ text: "SELECT * FROM pg_tables" });
// Clean up the client, ensuring we don't kill the worker before that is
// completed.
ctx.waitUntil(client.end());
// Return result rows as JSON
return Response.json({ result: result });
} catch (e) {
console.log(e);
return Response.json({ error: e.message }, { status: 500 });
}
},
} satisfies ExportedHandler<Env>;
```
## 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/).
---
# 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.
## Connection Pooling
Hyperdrive creates a global pool of connections to your database that can be reused as your application executes queries against your database.
When a query hits Hyperdrive, the request is routed to the nearest connection pool.
If the connection pool has pre-existing connections, the connection pool will try and reuse that 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.
:::
## 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.
## 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.
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.
## 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.
## Related resources
* [Query caching](/hyperdrive/configuration/query-caching/)
---
# 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.
<Render file="tutorials-before-you-start" product="workers" />
:::caution[Warning]
If your organization also uses [Super Bot Fight Mode](/bots/get-started/pro/), 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/configuration/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 using Postgres.js
Use Postgres.js to send a test query to validate that the connection has been successful.
<Render file="use-postgresjs-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/).
## 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.
---
# Configuration
URL: https://developers.cloudflare.com/hyperdrive/configuration/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# Query caching
URL: https://developers.cloudflare.com/hyperdrive/configuration/query-caching/
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:
```sql
-- Cacheable
SELECT * FROM articles
WHERE DATE(published_time) = CURRENT_DATE()
ORDER BY published_time DESC
LIMIT 50
```
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:
```sql
-- Not cached
INSERT INTO users(id, name, email) VALUES(555, 'Matt', 'hello@example.com');
SELECT LASTVAL(), * FROM articles LIMIT 50;
```
## 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 the [Postgres.js](/hyperdrive/configuration/connect-to-postgres/) driver:
```ts
const client = new Client({
connectionString: env.HYPERDRIVE.connectionString,
});
// ...
const noCachingClient = new Client({
// This represents a Hyperdrive configuration with the cache disabled
connectionString: env.HYPERDRIVE_CACHE_DISABLED.connectionString,
});
```
## Next steps
- Learn more about [How Hyperdrive works](/hyperdrive/configuration/how-hyperdrive-works/).
- Learn how to [Connect to PostgreSQL](/hyperdrive/configuration/connect-to-postgres/) from Hyperdrive.
- Review [Troubleshooting common issues](/hyperdrive/observability/troubleshooting/) when connecting a database to Hyperdrive.
---
# 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 any local database instance running on your machine directly. Local development uses [Wrangler](/workers/wrangler/install-and-update/), the command-line interface for Workers, to manage local development sessions and state.
## Configure local development
:::note
This guide assumes you are using `wrangler` version `3.27.0` or later.
If you are new to Hyperdrive and/or Cloudflare Workers, refer to [Hyperdrive tutorial](/hyperdrive/get-started/) to install `wrangler` and deploy their first database.
:::
To specify a database to connect to when developing locally, you can:
- **Recommended** Create a `WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>` environmental variable 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 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, 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/).
---
# 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 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.
:::
---
# Connect to AWS RDS and Aurora
URL: https://developers.cloudflare.com/hyperdrive/examples/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**.
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" />
---
# Connect to CockroachDB
URL: https://developers.cloudflare.com/hyperdrive/examples/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" />
---
# Connect to Azure Database
URL: https://developers.cloudflare.com/hyperdrive/examples/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" />
---
# Connect to Digital Ocean
URL: https://developers.cloudflare.com/hyperdrive/examples/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" />
:::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.
:::
---
# Connect to Google Cloud SQL
URL: https://developers.cloudflare.com/hyperdrive/examples/google-cloud-sql/
import { Render } from "~/components";
This example shows you how to connect Hyperdrive to a Google Cloud SQL PostgreSQL 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** > 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" />
---
# Examples
URL: https://developers.cloudflare.com/hyperdrive/examples/
import { GlossaryTooltip, ListExamples } from "~/components";
Explore the following <GlossaryTooltip term="code example">examples</GlossaryTooltip> for Hyperdrive.
<ListExamples directory="hyperdrive/examples/" />
---
# Connect to Neon
URL: https://developers.cloudflare.com/hyperdrive/examples/neon/
import { Render } from "~/components";
This example shows you how to connect Hyperdrive to a [Neon](https://neon.tech/) Postgres database.
## 1. Allow Hyperdrive access
You can connect Hyperdrive to any existing Neon database by creating a new user and fetching your database connection string.
### Neon Dashboard
1. Go to the [**Neon dashboard**](https://console.neon.tech/app/projects) and select the project (database) you wish to connect to.
2. Select **Roles** from the sidebar and select **New Role**. Enter `hyperdrive-user` as the name (or your preferred name) and **copy the password**. Note that the password will not be displayed again: you will have to reset it if you do not save it somewhere.
3. Select **Dashboard** from the sidebar > go to the **Connection Details** pane > ensure you have selected the **branch**, **database** and **role** (for example,`hyperdrive-user`) that Hyperdrive will connect through.
4. Select the `psql` and **uncheck the connection pooling** checkbox. Note down the connection string (starting with `postgres://hyperdrive-user@...`) from the text box.
With both the connection string and the password, you can now create a Hyperdrive database configuration.
## 2. Create a database configuration
<Render file="create-hyperdrive-config" />
---
# Connect to Materialize
URL: https://developers.cloudflare.com/hyperdrive/examples/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" />
---
# Connect to Nile
URL: https://developers.cloudflare.com/hyperdrive/examples/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" />
---
# Connect to pgEdge Cloud
URL: https://developers.cloudflare.com/hyperdrive/examples/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" />
---
# Connect to Supabase
URL: https://developers.cloudflare.com/hyperdrive/examples/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" />
---
# Connect to Timescale
URL: https://developers.cloudflare.com/hyperdrive/examples/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" />
---
# Connect to Xata
URL: https://developers.cloudflare.com/hyperdrive/examples/xata/
import { Render } from "~/components";
This example shows you how to connect Hyperdrive to a Xata PostgreSQL database instance.
## 1. Allow Hyperdrive access
You can connect Hyperdrive to any existing Xata database with the default user and password provided by Xata.
### Xata dashboard
To retrieve your connection string from the Xata dashboard:
1. Go to the [**Xata dashboard**](https://app.xata.io/).
2. Select the database you want to connect to.
3. Select **Settings**.
4. Copy the connection string from the `PostgreSQL endpoint` section and add your API key.
## 2. Create a database configuration
<Render file="create-hyperdrive-config" />
---
# Observability
URL: https://developers.cloudflare.com/hyperdrive/observability/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# 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. |
## 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. |
### 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. |
### 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.
---
# 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
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
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
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
}
}
}
}
}
```
---
# Changelog
URL: https://developers.cloudflare.com/hyperdrive/platform/changelog/
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 />
---
# Platform
URL: https://developers.cloudflare.com/hyperdrive/platform/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# 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 | Limit |
| ---------------------------------------------- | ------------------------------------------------------------------------------------- |
| Maximum configured databases | 25 per account |
| Initial connection timeout | 15 seconds |
| Idle connection timeout | 10 minutes |
| Maximum cached query response size | 50 MB |
| Maximum query (statement) duration | 60 seconds |
| Maximum username length | 63 characters (bytes) [^1] |
| Maximum database name length | 63 characters (bytes) [^1] |
| Maximum potential origin database connections | approx. \~100 connections [^2] |
:::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.
:::
---
# Pricing
URL: https://developers.cloudflare.com/hyperdrive/platform/pricing/
**Hyperdrive is free and included in every [Workers Paid](/workers/platform/pricing/#workers) plan**.
Hyperdrive is automatically enabled when subscribed to a Workers Paid plan, and does not require you to pay any additional fees to use. Hyperdrive's [connection pooling and query caching](/hyperdrive/configuration/how-hyperdrive-works/) do not incur any additional charges, and there are no hidden limits other than those [published](/hyperdrive/platform/limits/).
:::note
For questions about pricing, refer to the [pricing FAQs](/hyperdrive/reference/faq/#pricing).
:::
---
# FAQ
URL: https://developers.cloudflare.com/hyperdrive/reference/faq/
Below you will find answers to our most commonly asked questions regarding Hyperdrive.
## Pricing
### Does Hyperdrive charge for data transfer / egress?
No.
### Is Hyperdrive available on the [Workers Free](/workers/platform/pricing/#workers) plan?
Not at this time.
### 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
URL: https://developers.cloudflare.com/hyperdrive/reference/supported-databases/
## Database support
Details on which database engines and/or specific database providers are supported are detailed in the following table.
| Database Engine | Supported | Known supported versions | Details |
| --------------- | ------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------- |
| PostgreSQL | ✅ | `9.0` to `16.x` | Both self-hosted and managed (AWS, Google Cloud, Oracle) instances are supported. |
| Neon | ✅ | All | Neon currently runs Postgres 15.x |
| Supabase | ✅ | All | Supabase currently runs Postgres 15.x |
| Timescale | ✅ | All | See the [Timescale guide](/hyperdrive/examples/timescale/) to connect. |
| Materialize | ✅ | All | Postgres-compatible. Refer to the [Materialize guide](/hyperdrive/examples/materialize/) to connect. |
| CockroachDB | ✅ | All | Postgres-compatible. Refer to the [CockroachDB](/hyperdrive/examples/cockroachdb/) guide to connect. |
| MySQL | Coming soon | | |
| SQL Server | Not currently supported. | | |
| MongoDB | Not currently supported. | | |
## 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`)
---
# 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 />
---
# 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**.
---
# 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`
---
# 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 />
---
# 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.
---
# 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.
## 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.
---
# 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/).
---
# 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/bm-subscription/) 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/).
***
## 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.
---
# Bind to Workers API
URL: https://developers.cloudflare.com/images/transform-images/bindings/
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:
```txt
[images]
binding = "IMAGES" # i.e. available in your Worker on env.IMAGES
```
Within your Worker code, you can interact with this binding by using `env.IMAGES`.
## 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 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.
### `.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:
```js
​​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 })
.output({ format: "image/avif" })
).response();
return response;
```
### `.info()`
- Outputs information about the image, such as `format`, `fileSize`, `width`, and `height`.
In this example, the transformed image is outputted as a WebP.
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 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 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`.
---
# 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 },
];
}
```
---
# 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)
---
# 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:
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).
In **Sources**, you can configure the origins for transformations on your zone.
## 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.
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" />
### `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" />
## 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" />
### `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 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
* 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 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 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,
});
```
---
# 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/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/).
---
# 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
env.NAMESPACE.get(key);
```
The `get()` method returns a promise you can `await` on to get the value. If the key is not found, the promise will resolve with the literal value `null`.
#### Example
An example of reading a key from within a Worker:
```js
export default {
async fetch(request, env, ctx) {
try {
const value = await env.NAMESPACE.get("first-key");
if (value === null) {
return new Response("Value not found", { status: 404 });
}
return new Response(value);
} catch (e) {
return new Response(e.message, { status: 500 });
}
},
};
```
## Reference
The following methods are provided to read from KV:
- [get()](#get-method)
- [getWithMetadata()](#getwithmetadata-method)
### `get()` method
To get the value for a given key, call the `get()` method on any KV namespace you have bound to your Worker code:
```js
env.NAMESPACE.get(key, type?);
// OR
env.NAMESPACE.get(key, options?);
```
The `get()` method returns a promise you can `await` on to get the value. If the key is not found, the promise will resolve with the literal value `null`.
#### 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).
The `get()` method 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.
### `getWithMetadata()` method
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.
The `getWithMetadata()` method 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.
#### Example
An example of reading a key with metadata from within a Worker:
```js
export default {
async fetch(request, env, ctx) {
try {
const { value, metadata } =
await env.NAMESPACE.getWithMetadata("first-key");
if (value === null) {
return new Response("Value not found", { status: 404 });
}
return new Response(value);
} catch (e) {
return new Response(e.message, { status: 500 });
}
},
};
```
## 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.
## 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/).
---
# 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 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/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/).
---
# 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/" />
---
# Store and retrieve static assets with Workers KV
URL: https://developers.cloudflare.com/kv/examples/workers-kv-to-serve-assets/
import { Render, PackageManagers } 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 and images, or when generating dynamic HTML responses from static assets such as translations.
:::note[Note]
With [Workers KV](/kv), you can access, edit and store assets directly from your [Worker](/workers). If you need to serve assets as part of a front-end or full-stack web application, consider using [Cloudflare Pages](/pages/) or [Workers static assets](/workers/static-assets/), which provide a purpose-built deployment experience for web applications and their assets.
:::
<Render file="tutorials-before-you-start" product="workers" />
## 1. Create a new Worker 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={"example-kv-assets"}
/>
<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "hello-world",
type: "Hello World Worker",
lang: "TypeScript",
}}
/>
Then, move into your newly created application
```sh
cd example-kv-assets
```
We'll also install the dependencies we will need for this project.
```sh
npm install mime accept-language-parser
npm install --save-dev @types/accept-language-parser
```
## 2. Create a new KV namespace
Next, we will create a KV store. This can be done through the Cloudflare dashboard or the Wrangler CLI. For this example, we will use the Wrangler CLI.
To create a KV store via Wrangler:
1. Open your terminal and run the following command:
```sh
npx wrangler kv namespace create assets
```
The `wrangler kv namespace create assets` subcommand creates a KV namespace by concatenating your Worker's name and the value provided for `assets`. An `id` will be randomly generated for the KV namespace.
```sh
npx wrangler kv namespace create assets
```
```sh {6} output
🌀 Creating namespace with title "example-kv-assets-assets"
✨ Success!
Add the following to your configuration file in your kv_namespaces array:
[[kv_namespaces]]
binding = "assets"
id = "<GENERATED_NAMESPACE_ID>"
```
2. In your Wrangler file, add the following with the values generated in the terminal:
```bash {3} title="wrangler.toml"
[[kv_namespaces]]
binding = "assets"
id = "<GENERATED_NAMESPACE_ID>"
```
The [KV binding](/kv/concepts/kv-bindings/) `assets` is how your Worker will interact with the [KV namespace](/kv/concepts/kv-namespaces/). This binding will be provided as a runtime variable within your Workers code by the Workers runtime.
We'll also create a preview KV namespace. It is recommended to create a separate KV namespace when developing locally to avoid making changes to the production namespace. When developing locally against remote resources, the Wrangler CLI will only use the namespace specified by `preview_id` in the KV namespace configuration of the Wrangler file.
3. In your terminal, run the following command:
```sh
npx wrangler kv namespace create assets --preview
```
This command will create a special KV namespace that will be used only when developing with Wrangler against remote resources using `wrangler dev --remote`.
```sh
npx wrangler kv namespace create assets --preview
```
```sh {6} output
🌀 Creating namespace with title "example-kv-assets-assets_preview"
✨ Success!
Add the following to your configuration file in your kv_namespaces array:
[[kv_namespaces]]
binding = "assets"
preview_id = "<GENERATED_PREVIEW_NAMESPACE_ID>"
```
4. In your Wrangler file, add the additional preview_id below kv_namespaces with the values generated in the terminal:
```bash {4} title="wrangler.toml"
[[kv_namespaces]]
binding = "assets"
id = "<GENERATED_NAMESPACE_ID>"
preview_id = "<GENERATED_PREVIEW_NAMESPACE_ID>"
```
We now have one KV binding that will use the production KV namespace when deployed and the preview KV namespace when developing locally against remote resources with `wrangler dev --remote`.
## 3. Store static assets in KV using Wrangler
To store static assets in KV, you can use the Wrangler CLI, the KV binding from a Worker application, or the KV REST API. We'll demonstrate how to use the Wrangler CLI.
For this scenario, we'll be storing a sample HTML file within our KV store. Create a new file `index.html` in the root of project 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 --binding assets --preview false
npx wrangler kv key put index.html --path index.html --binding assets --preview
```
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.
## 4. Serve static assets from KV from your Worker application
Within the `index.ts` file of our Worker project, replace the contents with the following:
```js title="index.ts"
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 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 new Response(value, {
status: 200,
headers: new Headers({
"Content-Type": mimeType
})
});
},
} satisfies ExportedHandler<Env>;
```
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 indicate to 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.
To start the Worker, run the following within a terminal:
```sh
npx wrangler dev --remote
```
This will run you Worker code against your remote resources, specifically using the preview KV namespace as configured.
```sh
npx wrangler dev --remote
```
```sh output
Your worker has access to the following bindings:
- KV Namespaces:
- assets: <GENERATED_PREVIEW_NAMESPACE_ID>
[wrangler:inf] Ready on http://localhost:<PORT>
```
Access the URL provided by the Wrangler command as such `http://localhost:<PORT>/index.html`. You will be able to see the returned HTML file containing the file contents of our `index.html` file that was added to our KV store. Try it out with an image or a document and you will see that this Worker is also properly serving those assets from KV.
## 5. Create an endpoint to generate dynamic responses from your key-value pairs
We'll add a `hello-world` endpoint to our Workers application, which will return a "Hello World!" message based on the language requested to demonstrate how to generate a dynamic response from our KV-stored assets.
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": "مرØبا بالعالم!"
}
]
```
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 --binding assets --preview false
npx wrangler kv key put hello-world.json --path hello-world.json --binding assets --preview
```
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:
```js {2, 26-63} title="index.ts"
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
if(key === 'hello-world'){
//retrieve the language header from the request and the translations from 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 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 new Response(value, {
status: 200,
headers: new Headers({
"Content-Type": mimeType
})
});
},
} satisfies ExportedHandler<Env>;
```
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.
```sh
npx wrangler dev --remote
```
With the Worker code running, 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).
## 6. Deploy your project
Run `wrangler deploy` to deploy your Workers project to Cloudflare with the binding to the KV namespace.
```sh
npx wrangler deploy
```
Wrangler will automatically set your KV binding to use the production KV namespace set in our Wrangler file with the KV namespace id. Throughout this example, we uploaded our assets to both the preview and the production KV namespaces.
We can now verify that our project is properly working by accessing our Workers default hostname and accessing `<WORKER-SUBDOMAIN>.<DEFAULT-ACCOUNT-HOSTNAME>.dev/index.html` or `<WORKER-SUBDOMAIN>.<DEFAULT-ACCOUNT-HOSTNAME>.dev/hello-world` to see our deployed Worker in action, generating responses from the values in our KV store.
## Related resources
- [Rust support in Workers](/workers/languages/rust/).
- [Using KV in Workers](/kv/get-started/).
---
# Key concepts
URL: https://developers.cloudflare.com/kv/concepts/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# 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/tutorial/#3-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);
}
}
```
---
# 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 highly dynamic APIs.
While reads are periodically revalidated in the background, requests which are not in cache and need to hit the centralized back end can experience high 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.
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.
:::
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 keep the latest value in the cache by refreshing from upper tiers and the central data stores 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.
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.
KV does not perform like an in-memory datastore, such as [Redis](https://redis.io). Accessing KV values, even when locally cached, has significantly more latency than reading a value from memory within a Worker script.
## 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.
## Security
Refer to [Data security documentation](/kv/reference/data-security/) to understand how Workers KV secures data.
---
# 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**.
---
# Observability
URL: https://developers.cloudflare.com/kv/observability/
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 (`date_geq` and `date_leq`), grouped by `date` and `actionType`:
```graphql
query {
viewer {
accounts(filter: { accountTag: $accountTag }) {
kvOperationsAdaptiveGroups(
filter: { namespaceId: $namespaceId, date_geq: $date_geq, date_leq: $date_leq }
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 (`date_geq`, `date_leq`):
```graphql
query {
viewer {
accounts(filter: { accountTag: $accountTag }) {
kvOperationsAdaptiveGroups(
filter: { namespaceId: $namespaceId, date_geq: $date_geq, date_leq: $date_leq, 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
query {
viewer {
accounts(filter: { accountTag: $accountTag }) {
kvOperationsAdaptiveGroups(filter: { date_geq: $date_geq, date_leq: $date_leq }, 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
query Viewer {
viewer {
accounts(filter: { accountTag: $accountTag }) {
kvStorageAdaptiveGroups(
filter: { date_geq: $date_geq, date_leq: $date_leq, namespaceId: $namespaceId }
limit: 10000
orderBy: [date_DESC]
) {
max {
keyCount
byteCount
}
dimensions {
date
}
}
}
}
}
```
---
# Changelog
URL: https://developers.cloudflare.com/kv/platform/changelog/
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 />
---
# 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 | 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 |
<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).
:::
---
# Platform
URL: https://developers.cloudflare.com/kv/platform/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# 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/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.
---
# Tutorials
URL: https://developers.cloudflare.com/kv/tutorials/
import { GlossaryTooltip, ListTutorials } from "~/components"
View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with KV.
<ListTutorials />
---
# 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/).
## Pricing
### When writing via Workers KV's [REST API](/api/resources/kv/subresources/namespaces/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.
---
# 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>
```
---
# Reference
URL: https://developers.cloudflare.com/kv/reference/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# 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.
---
# Reference
URL: https://developers.cloudflare.com/privacy-gateway/reference/
import { DirectoryListing } from "~/components"
<DirectoryListing />
---
# 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.
---
# 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.
---
# 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/
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:
```sh
# Pre-requisite: install MQTT.js
npm install mqtt --save
```
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 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");
}
```
---
# 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()
```
---
# Examples
URL: https://developers.cloudflare.com/pub-sub/examples/
import { ListExamples } from "~/components";
<ListExamples directory="pub-sub/examples/" />
---
# 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).
---
# 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`.
---
# 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.
---
# 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.
---
# Integrate with Workers
URL: https://developers.cloudflare.com/pub-sub/learning/integrate-workers/
import { WranglerConfig } 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>
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.
/// <reference types="@cloudflare/workers-types" />
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.
---
# 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.
---
# WebSockets and Browser Clients
URL: https://developers.cloudflare.com/pub-sub/learning/websockets-browsers/
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.
```js
// Ensure MQTT.js is installed first
// > npm install mqtt
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.
---
# Learning
URL: https://developers.cloudflare.com/pub-sub/learning/
import { DirectoryListing } from "~/components"
<DirectoryListing />
---
# 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/setup/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 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](/pages/configuration/build-image/#overriding-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](/pages/configuration/build-image/#overriding-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` |
## V2 build system
The [v2 build system](https://blog.cloudflare.com/moderizing-cloudflare-pages-builds-toolbox/) announced in May 2023 brings several improvements to project builds.
### V1 to V2 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 v2. 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
Here are some limitations with the v2 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 />
---
# 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 |
| --------------------- | ------------------------------------- | --------------------------------------------------------------------------------------- |
| `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 |
---
# 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 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: \`\`
---
# Custom domains
URL: https://developers.cloudflare.com/pages/configuration/custom-domains/
When deploying your Pages project, you may wish to point custom domains (or subdomains) to your site.
## Add a custom domain
To add a custom domain:
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login).
2. Select your account in **Account Home** > **Workers & Pages**.
3. Select your Pages project > **Custom domains**.
4. Select **Set up a domain**.
5. Provide the domain that you would like to serve your Cloudflare Pages site on and select **Continue**.
### 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/setup/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/cloudflare-errors/troubleshooting-cloudflare-5xx-errors/#error-522-connection-timed-out).
:::
## 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.
---
# 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**.
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/setup/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/setup/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/setup/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.
## 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
## 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.
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.
## 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.
### 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.
### 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:
### 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.
### 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.
### 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**.
---
# 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/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"
## Attach a header
To attach headers to Cloudflare Pages responses, create a `_headers` plain text file in the output folder of your project. It is usually the folder that contains the deploy-ready HTML files and assets generated by the build, such as favicons. Changes to headers will be updated to your website at build time. Make sure you commit and push the file to trigger a new build each time you update headers.
:::caution
Custom headers defined in the `_headers` file are not applied to responses from [Functions](/pages/functions/), even if the Function route matches the URL pattern. If your Pages application uses Functions, you must migrate any behaviors from the `_headers` file to the `Response` object in the appropriate `/functions` route. When altering headers for multiple routes, you may be interested in [adding middleware](/pages/functions/middleware/) for shared behavior.
:::
Header rules are defined in multi-line blocks. The first line of a block is the URL or URL pattern where the rule's headers should be applied. On the next line, an indented list of header names and header values must be written:
```txt
[url]
[name]: [value]
```
Using absolute URLs is supported, though be aware that absolute URLs must begin with `https` and specifying a port is not supported. Cloudflare Pages ignores the incoming request's port and protocol when matching against an incoming request. For example, a rule like `https://example.com/path` would match against requests to `other://example.com:1234/path`.
You can define as many `[name]: [value]` pairs as you require on subsequent lines. For example:
```txt
# This is a comment
/secure/page
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Referrer-Policy: no-referrer
/static/*
Access-Control-Allow-Origin: *
X-Robots-Tag: nosnippet
https://myproject.pages.dev/*
X-Robots-Tag: noindex
```
An incoming request which matches multiple rules' URL patterns will inherit all rules' headers. Using the previous `_headers` file, the following requests will have the following headers applied:
| Request URL | Headers |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `https://custom.domain/secure/page` | `X-Frame-Options: DENY` <br /> `X-Content-Type-Options: nosniff ` <br /> `Referrer-Policy: no-referrer` |
| `https://custom.domain/static/image.jpg` | `Access-Control-Allow-Origin: *` <br /> `X-Robots-Tag: nosnippet` |
| `https://myproject.pages.dev/home` | `X-Robots-Tag: noindex` |
| `https://myproject.pages.dev/secure/page` | `X-Frame-Options: DENY` <br /> `X-Content-Type-Options: nosniff` <br /> `Referrer-Policy: no-referrer` <br /> `X-Robots-Tag: noindex` |
| `https://myproject.pages.dev/static/styles.css` | `Access-Control-Allow-Origin: *` <br /> `X-Robots-Tag: nosnippet, noindex` |
A project is limited to 100 header rules. Each line in the `_headers` file has a 2,000 character limit. The entire line, including spacing, header name, and value, counts towards this limit.
If a header is applied twice in the `_headers` file, the values are joined with a comma separator. Headers defined in the `_headers` file override what Cloudflare Pages ordinarily sends, so be aware when setting security headers. Cloudflare reserves the right to attach new headers to Pages projects at any time in order to improve performance or harden the security of your deployments.
### Detach a header
You may wish to remove a header which has been added by a more pervasive rule. This can be done by prepending an exclamation mark `!`.
```txt
/*
Content-Security-Policy: default-src 'self';
/*.jpg
! Content-Security-Policy
```
### Match a path
The same URL matching features that [`_redirects`](/pages/configuration/redirects/) offers is also available to the `_headers` file. Note, however, that redirects are applied before headers, when a request matches both a redirect and a header, the redirect takes priority.
#### Splats
When matching, a splat pattern — signified by an asterisk (`*`) — will greedily match all characters. You may only include a single splat in the URL.
The matched value can be referenced within the header value as the `:splat` placeholder.
#### Placeholders
<Render file="headers_redirects_placeholders" params={{ one: "header" }} />
```txt
/movies/:title
x-movie-name: You are watching ":title"
```
## Examples
### Cross-Origin Resource Sharing (CORS)
To enable other domains to fetch every asset from your Pages project, the following can be added to the `_headers` file:
```txt
/*
Access-Control-Allow-Origin: *
```
This applies the `Access-Control-Allow-Origin` header to any incoming URL. To be more restrictive, you can define a URL pattern that applies to a `*.pages.dev` subdomain, which then only allows access from its `staging` branch's subdomain:
```txt
https://:project.pages.dev/*
Access-Control-Allow-Origin: https://staging.:project.pages.dev/
```
### Prevent your pages.dev deployments showing in search results
[Google](https://developers.google.com/search/docs/advanced/robots/robots_meta_tag#directives) and other search engines often support the `X-Robots-Tag` header to instruct its crawlers how your website should be indexed.
For example, to prevent your `*.pages.dev` deployment from being indexed, add the following to your `_headers` file:
```txt
https://:project.pages.dev/*
X-Robots-Tag: noindex
```
### Harden security for an application
:::note
If you are using Pages Functions and wish to attach security headers in order to control access to or browser behavior of server-side logic, the headers should be sent from in Pages Functions' `Response` instead of the `_headers` file. For example, if you have an API endpoint and want to allow cross-origin requests, you should ensure that your Pages Functions attaches CORS headers to its responses, including to `OPTIONS` requests. This is to ensure that, in the unlikely event of an incident involving serving static assets, your API security headers will continue to be configured.
:::
You can prevent click-jacking by informing browsers not to embed your application inside another (for example, with an `<iframe>`) with a [`X-Frame-Options`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options) header.
[`X-Content-Type-Options: nosniff`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options) prevents browsers from interpreting a response as any other content-type than what is defined with the `Content-Type` header.
[`Referrer-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy) allows you to customize how much information visitors give about where they are coming from when they navigate away from your page.
Browser features can be disabled to varying degrees with the [`Permissions-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Feature-Policy) header (recently renamed from `Feature-Policy`).
If you need fine-grained control over your application's content, the [`Content-Security-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) header allows you to configure a number of security settings, including similar controls to the `X-Frame-Options` header.
```txt
/app/*
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Referrer-Policy: no-referrer
Permissions-Policy: document-domain=()
Content-Security-Policy: script-src 'self'; frame-ancestors 'none';
```
---
# Configuration
URL: https://developers.cloudflare.com/pages/configuration/
import { DirectoryListing } from "~/components"
<DirectoryListing />
---
# 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.
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:
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.
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.
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.
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/setup/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"
To use redirects on Cloudflare Pages, declare your redirects in a plain text file called `_redirects` without a file extension, in the output folder of your project. The [build output folder](/pages/configuration/build-configuration/) is project-specific, so the `_redirects` file should not always be in the root directory of the repository. Changes to redirects will be updated to your website at build time so make sure you commit and push the file to trigger a new build each time you update redirects.
:::caution
Redirects defined in the `_redirects` file are not applied to requests served by [Functions](/pages/functions/), even if the Function route matches the URL pattern. If your Pages application uses Functions, you must migrate any behaviors from the `_redirects` file to the code in the appropriate `/functions` route, or [exclude the route from Functions](/pages/functions/routing/#create-a-_routesjson-file).
:::
## Structure
### Per line
Only one redirect can be defined per line and must follow this format, otherwise it will be ignored.
```txt
[source] [destination] [code?]
```
* `source` required
* A file path.
* Can include [wildcards (`*`)](#splats) and [placeholders](#placeholders).
* Because fragments are evaluated by your browser and not Cloudflare's network, any fragments in the source are not evaluated.
* `destination` required
* A file path or external link.
* Can include fragments, query strings, [splats](#splats), and [placeholders](#placeholders).
* `code` default: `302`
* Optional parameter
Lines starting with a `#` will be treated as comments.
### Per file
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.
In your `_redirects` file:
* The order of your redirects matter. If there are multiple redirects for the same `source` path, the topmost redirect is applied.
* Static redirects should appear before dynamic redirects.
* Redirects are always followed, regardless of whether or not an asset matches the incoming request.
A complete example with multiple redirects may look like the following:
```txt
/home301 / 301
/home302 / 302
/querystrings /?query=string 301
/twitch https://twitch.tv
/trailing /trailing/ 301
/notrailing/ /nottrailing 301
/page/ /page2/#fragment 301
/blog/* https://blog.my.domain/:splat
/products/:code/:name /products?code=:code&name=:name
```
:::note
In the case of some frameworks, such as Jekyll, you may need to manually copy and paste your `_redirects` file to the build output directory. To do this:
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to **Workers & Pages** > your Pages project > **Settings** > **Builds & deployments**.
3. Go to **Build configurations** > **Edit configurations** > change the build command to `jekyll build && cp _redirects _site/_redirects` and select **Save**.
:::
## Advanced redirects
Cloudflare currently offers limited support for advanced redirects. More support will be added in the future.
| Feature | Support | Example | Notes |
| ----------------------------------- | ------- | --------------------------------------------------------------- | --------------------------------------- |
| Redirects (301, 302, 303, 307, 308) | Yes | `/home / 301` | 302 is used as the default status code. |
| Rewrites (other status codes) | No | `/blog/* /blog/404.html 404` | |
| Splats | Yes | `/blog/* /posts/:splat` | Refer to [Splats](#splats). |
| Placeholders | Yes | `/blog/:year/:month/:date/:slug /news/:year/:month/:date/:slug` | Refer to [Placeholders](#placeholders). |
| Query Parameters | No | `/shop id=:id /blog/:id 301` | |
| Proxying | Yes | `/blog/* /news/:splat 200` | Refer to [Proxying](#proxying). |
| Domain-level redirects | No | `workers.example.com/* workers.example.com/blog/:splat 301` | |
| Redirect by country or language | No | `/ /us 302 Country=us` | |
| Redirect by cookie | No | `/\* /preview/:splat 302 Cookie=preview` | |
## Redirects and header matching
Redirects execute before headers, so in the case of a request matching rules in both files, the redirect will win out.
### Splats
On matching, a splat (asterisk, `*`) will greedily match all characters. You may only include a single splat in the URL.
The matched value can be used in the redirect location with `:splat`.
### Placeholders
<Render file="headers_redirects_placeholders" params={{ one: "redirect" }} />
```txt
/movies/:title /media/:title
```
### Proxying
Proxying will only support relative URLs on your site. You cannot proxy external domains.
Only the first redirect in your will apply. For example, in the following example, a request to `/a` will render `/b`, and a request to `/b` will render `/c`, but `/a` will not render `/c`.
```
/a /b 200
/b /c 200
```
:::note
Be aware that proxying pages can have an adverse effect on search engine optimization (SEO). Search engines often penalize websites that serve duplicate content. Consider adding a `Link` HTTP header which informs search engines of the canonical source of content.
For example, if you have added `/about/faq/* /about/faqs 200` to your `_redirects` file, you may want to add the following to your `_headers` file:
```txt
/about/faq/*
Link: </about/faqs>; rel="canonical"
```
:::
## Surpass `_redirects` limits
A [`_redirects`](/pages/platform/limits/#redirects) file has a maximum of 2,000 static redirects and 100 dynamic redirects, for a combined total of 2,100 redirects. Use [Bulk Redirects](/rules/url-forwarding/bulk-redirects/) to handle redirects that surpasses the 2,100 redirect rules limit set by Pages.
:::note
The redirects defined in the `_redirects` file of your build folder can work together with your Bulk Redirects. In case of duplicates, Bulk Redirects will run in front of your Pages project, where your other redirects live.
For example, if you have Bulk Redirects set up to direct `abc.com` to `xyz.com` but also have `_redirects` set up to direct `xyz.com` to `foo.com`, a request for `abc.com` will eventually redirect to `foo.com`.
:::
To use Bulk Redirects, refer to the [Bulk Redirects dashboard documentation](/rules/url-forwarding/bulk-redirects/create-dashboard/) or the [Bulk Redirects API documentation](/rules/url-forwarding/bulk-redirects/create-api/).
## Related resources
* [Transform Rules](/rules/transform/)
---
# 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.
## Related resources
* [Preview Deployments](/pages/configuration/preview-deployments/)
* [Branch deployment controls](/pages/configuration/branch-build-controls/)
---
# 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
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**.
3. Select **Create application** > **Pages** > **Connect to Git**.
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 | `./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" }} />
---
# 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
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, select _Brunch_ as your **Framework preset**. Your selection will provide the following information.
<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" }} />
---
# 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.
---
# 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"
/>
`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
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, select _Docusaurus_ as your **Framework preset**. Your selection will provide the following information.
<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" }} />
---
# 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
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:
<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:
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, the following information will be provided:
<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
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 | `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`).
<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"
/>
Open your project and create a `src/server.js` file (or `src/server.ts` if you are using TypeScript). Add the following content to your file:
```javascript
import { Hono } from "hono";
const app = new Hono();
app.get("/", (ctx) => ctx.text("Hello world, this is Hono!!"));
export default app;
```
To serve static files like CSS, image or JavaScript files, add the following to your `src/server.js/ts` file:
```javascript
app.get("/public/*", async (ctx) => {
return await ctx.env.ASSETS.fetch(ctx.req.raw);
});
```
This will cause all the files in the `public` folder within `dist` to be served in your application.
:::note
The `dist` directory is created and used during the bundling process. You will need to create a `public` directory in the `dist` directory. Having `public` inside `dist` is not generally wanted as `dist` is not a directory to commit to your repository whilst `public` is.
There are different alternatives to fix this issue. For example, you can configure your `.gitignore` file to include the `dist` directory, but ignore all its context except the `public` directory. Alternatively, you can create a `public` directory somewhere else and copy it inside `dist` as part of the bundling process.
:::
Open your `package.json` file and update the `scripts` section:
<Tabs> <TabItem label="JavaScript" icon="seti:javascript">
```json
"scripts": {
"dev": "run-p dev:*",
"dev:wrangler": "wrangler pages dev dist --live-reload",
"dev:esbuild": "esbuild --bundle src/server.js --format=esm --watch --outfile=dist/_worker.js",
"build": "esbuild --bundle src/server.js --format=esm --outfile=dist/_worker.js",
"deploy": "wrangler pages publish dist"
},
```
</TabItem> <TabItem label="TypeScript" icon="seti:typescript">
```json
"scripts": {
"dev": "run-p dev:*",
"dev:wrangler": "wrangler pages dev dist --live-reload",
"dev:esbuild": "esbuild --bundle src/server.ts --format=esm --watch --outfile=dist/_worker.js",
"build": "esbuild --bundle src/server.ts --format=esm --outfile=dist/_worker.js",
"deploy": "wrangler pages publish dist"
},
```
</TabItem> </Tabs>
Then, run the following command.
```sh
npm install npm-run-all --save-dev
```
Installing `npm-run-all` enables you to use a single command (`npm run dev`) to run `npm run dev:wrangler` and `npm run dev:esbuild` simultaneously in watch mode.
## Run in local dev
Start your dev workflow by running:
```sh
npm run 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
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 | `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
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:
<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" }} />
---
# 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"
/>
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
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. Go to **Workers & Pages** > **Create application** > **Pages** > **Connect to Git** and create a new Pages project.
You will be asked to authorize access to your GitHub account if you have not already done so. Cloudflare needs this so that it can monitor and deploy your projects from the source. You may narrow access to specific repositories if you prefer; however, you will have to manually update this list [within your GitHub settings](https://github.com/settings/installations) when you want to add more repositories to Cloudflare Pages.
3. Select the new GitHub repository that you created and, in the **Set up builds and deployments** section, provide the following information:
<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/).
The following is an example of adding a `KVNamespace` binding:
```ts null {9}
import {
CfProperties,
Request,
ExecutionContext,
KVNamespace,
} from "@cloudflare/workers-types";
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" />
---
# 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
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:
<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" }} />
---
# 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
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**.
You will be asked to authorize access to your GitHub account if you have not already done so. Cloudflare needs this so that it can monitor and deploy your projects from the source. You may narrow access to specific repositories if you prefer; however, you will have to manually update this list [within your GitHub settings](https://github.com/settings/installations) when you want to add more repositories to Cloudflare Pages.
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 | `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"
/>
`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
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:
<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 the @cloudflare/workers-types package
const { MY_KV } = (platform.env as { MY_KV: KVNamespace }));
return {
// ....
}
});
```
<Render file="framework-guides/learn-more" params={{ one: "Qwik" }} />
---
# 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
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, select _Pelican_ as your **Framework preset**. Your selection will provide the following information. The build command `pelican content` refers to the `content` folder you made earlier in this guide.
<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" }} />
---
# 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"
/>
`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
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:
<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" }} />
---
# 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"
/>
`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 start
```
<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" }} />
---
# 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
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 **Set up builds and deployments**, provide the following information:
<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
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 | `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";
[Svelte](https://svelte.dev) is an increasingly popular, open-source framework for building user interfaces and web applications. Unlike most frameworks, Svelte is primarily a compiler that converts your component code into efficient JavaScript that surgically updates the DOM when your application state changes.
In this guide, you will create a new Svelte 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 Svelte's official setup tool, and provide the option to deploy instantly.
To use `create-cloudflare` to create a new Svelte project, run the following command:
<PackageManagers
type="create"
pkg="cloudflare@latest"
args="my-svelte-app --framework=svelte"
/>
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 `@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
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**.
You will be asked to authorize access to your GitHub account if you have not already done so. Cloudflare needs this authorization to deploy your projects from your GitHub account. You may narrow Cloudflare's access to specific repositories. However, you will have to manually update this list [within your GitHub settings](https://github.com/settings/installations) when you want to add more repositories to Cloudflare Pages.
Select the new GitHub repository that you created and, in **Set up builds and deployments**, provide the following information:
<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 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 } 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:
<Tabs> <TabItem label="npm">
```sh
npx vitepress@latest init
```
</TabItem> <TabItem label="pnpm">
```sh
pnpm dlx vitepress@latest init
```
</TabItem> <TabItem label="yarn">
```sh
yarn dlx vitepress@latest init
```
</TabItem> <TabItem label="bun">
```sh
bunx vitepress@latest init
```
</TabItem> </Tabs>
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:
<Tabs> <TabItem label="npm">
```sh
npm add -D vitepress
```
</TabItem> <TabItem label="pnpm">
```sh
pnpm add -D vitepress
```
</TabItem> <TabItem label="yarn">
```sh
yarn add -D vitepress
```
</TabItem> <TabItem label="bun">
```sh
bun add -D vitepress
```
</TabItem> </Tabs>
:::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
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, the following information will be provided:
<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"
/>
<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
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="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" }} />
---
# 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"
/>
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
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. Go to **Workers & Pages** > **Create application** > **Pages** > **Connect to Git** and create a new Pages project.
You will be asked to authorize access to your GitHub account if you have not already done so. Cloudflare needs this so that it can monitor and deploy your projects from the source. You may narrow access to specific repositories if you prefer; however, you will have to manually update this list [within your GitHub settings](https://github.com/settings/installations) when you want to add more repositories to Cloudflare Pages.
3. Select the new GitHub repository that you created and, in the **Set up builds and deployments** section, provide the following information:
<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.
---
# 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"
/>
`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
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. Go to **Workers & Pages** > **Create application** > **Pages** > **Connect to Git** and create a new Pages project.
You will be asked to authorize access to your GitHub account if you have not already done so. Cloudflare needs this so that it can monitor and deploy your projects from the source. You may narrow access to specific repositories if you prefer; however, you will have to manually update this list [within your GitHub settings](https://github.com/settings/installations) when you want to add more repositories to Cloudflare Pages.
3. Select the new GitHub repository that you created and, in the **Set up builds and deployments** section, provide the following information:
<PagesBuildPreset framework="angular" />
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" }} />
---
# 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
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:
<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" }} />
---
# 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"
/>
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
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**.
You will be asked to authorize access to your GitHub account if you have not already done so. Cloudflare needs this so that it can monitor and deploy your projects from the source. You may narrow access to specific repositories if you prefer; however, you will have to manually update this list [within your GitHub settings](https://github.com/settings/installations) when you want to add more repositories to Cloudflare Pages.
Select the new GitHub repository that you created and, in the **Set up builds and deployments** section, provide the following information:
<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`:
```typescript
/// <reference types="astro/client" />
type KVNamespace = import("@cloudflare/workers-types").KVNamespace;
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) {
// the type KVNamespace comes from the @cloudflare/workers-types package
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" }} />
---
# 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
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**.
You will be asked to authorize access to your GitHub account if you have not already done so. Cloudflare needs this so that it can monitor and deploy your projects from the source. You may narrow access to specific repositories if you prefer; however, you will have to manually update this list [within your GitHub settings](https://github.com/settings/installations) when you want to add more repositories to Cloudflare Pages.
Select the new GitHub repository that you created and, in the **Set up builds and deployments** section, provide the following information:
<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" }} />
---
# 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
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, select _Eleventy_ as your **Framework preset**. Your selection will provide the following information:
<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
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, select _Ember_ as your **Framework preset**. Your selection will provide the following information:
<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" }} />
---
# 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
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, select _MkDocs_ as your **Framework preset**. Your selection will provide the following information:
<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" }} />
---
# 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
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 (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: " " }} />
---
# Framework guides
URL: https://developers.cloudflare.com/pages/framework-guides/
import { DirectoryListing } from "~/components"
<DirectoryListing />
---
# 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`
* <code>onRequest(context[EventContext](#eventcontext))</code> Response | Promise\<Response>
* This function will be invoked on all requests no matter the request method.
* <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.
---
# 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:
Your dashboard will display:
## 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).
---
# 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/local-development/).
:::
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/local-development/).
:::
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" />
---
# 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.
---
# 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.
---
# 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" }
}
);
}
```
---
# 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, SvelteKit) 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/*"]
}
```
### 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.
:::
## 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/
Pages Functions supports TypeScript. Author any files in your `/functions` directory with a `.ts` extension instead of a `.js` extension to start using TypeScript.
To add the runtime types to your project, run:
```sh
npm install --save-dev typescript @cloudflare/workers-types
```
Then configure the runtime types by creating a `functions/tsconfig.json` file:
```json
{
"compilerOptions": {
"target": "esnext",
"module": "esnext",
"lib": ["esnext"],
"types": ["@cloudflare/workers-types"]
}
}
```
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. To use the `env` parameter:
```ts
interface Env {
KV: KVNamespace;
}
export const onRequest: PagesFunction<Env> = async (context) => {
const value = await context.env.KV.get("example");
return new Response(value);
};
```
---
# 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="workers" />
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.
## 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:
<Tabs> <TabItem label="npm">
```sh
npm create cloudflare@latest [--] [<DIRECTORY>] [OPTIONS] [-- <NESTED ARGS...>]
```
</TabItem> <TabItem label="yarn">
```sh
yarn create cloudflare [--] [<DIRECTORY>] [OPTIONS] [-- <NESTED ARGS...>]
```
</TabItem> <TabItem label="pnpm">
```sh
pnpm create cloudflare@latest [--] [<DIRECTORY>] [OPTIONS] [-- <NESTED ARGS...>]
```
</TabItem> </Tabs>
- `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..` string\[] 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` boolean (default: true) optional
- Deploy your application after it has been created.
- `--lang`string (default: ts) optional
- The programming language of the template.
- The possible values for this option are:
- `ts`
- `js`
- `python`
- `--ts`boolean (default: true) optional
- Use TypeScript in your application. Deprecated. Please use `--lang=ts` instead.
- `--git` boolean (default: true) optional
- Initialize a local git repository for your application.
- `--open` boolean (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` boolean (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"
/>
---
# 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/local-development/) 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/local-development/) 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/local-development/) 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.
---
# 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" />
---
# Get started
URL: https://developers.cloudflare.com/pages/get-started/
import { DirectoryListing } from "~/components"
Choose a setup method for your Pages project:
<DirectoryListing />
---
# 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/setup/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.
---
# 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/setup/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`.
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 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`.
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.
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`:
## 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/
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**.
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@v3
# Run your project's build step
# - name: Build
# run: npm install && npm run build
- name: Publish
uses: cloudflare/pages-action@v1
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
projectName: YOUR_PROJECT_NAME # e.g. 'my-project'
directory: YOUR_DIRECTORY_OF_STATIC_ASSETS # e.g. 'dist'
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`).
### 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 }
```
In the code block above you have specified the language as `node_js` and listed the value as `18.0.0` because Wrangler v2 depends on this Node version or higher. 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" />
---
# Migration guides
URL: https://developers.cloudflare.com/pages/migrations/
import { DirectoryListing } from "~/components"
<DirectoryListing />
---
# 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/)
---
# 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.
---
# Tutorials
URL: https://developers.cloudflare.com/pages/tutorials/
import { GlossaryTooltip, ListTutorials } from "~/components"
View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with Pages.
<ListTutorials />
---
# 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.
---
# 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.
---
# 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-standard-usage-model) 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
# Confirm we are using wrangler v3.1.0+
wrangler --version
```
```sh output
â›…ï¸ wrangler 3.1.0
```
Start a local dev session
```sh
# Start a local dev session:
npx 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
⎔ Starting local server...
[mf:inf] Ready on http://127.0.0.1:8787/
```
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.
## Known Issues
Wrangler does not yet support running separate producer and consumer Workers bound to the same Queue locally. To develop locally with Queues, you can temporarily put your consumer's `queue()` handler in the same Worker as your producer, so the same Worker acts as both a producer and consumer.
Wrangler also does not yet support `wrangler dev --remote`.
---
# 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, noting that all consumers will share the same [rate limit](/queues/platform/limits/) against the Cloudflare API.
### 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 avoid hitting [API rate limits](/queues/platform/limits/).
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.
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.
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_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")
}
```
---
# 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 />
---
# Platform
URL: https://developers.cloudflare.com/queues/platform/
import { DirectoryListing } from "~/components"
<DirectoryListing />
---
# Audit Logs
URL: https://developers.cloudflare.com/queues/platform/audit-logs/
[Audit logs](/fundamentals/setup/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/setup/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>
---
# Limits
URL: https://developers.cloudflare.com/queues/platform/limits/
import { Render } 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> | 14 days |
| 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 | 30 seconds |
| `visibilityTimeout` (pull-based queues) | 12 hours |
| `delaySeconds` (when sending or retrying) | 12 hours |
| Requests to the Queues API (incl. pulls/acks) | [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).
<Render file="limits_increase" product="workers" />
---
# Observability
URL: https://developers.cloudflare.com/queues/observability/
import { DirectoryListing } from "~/components"
<DirectoryListing />
---
# Metrics
URL: https://developers.cloudflare.com/queues/observability/metrics/
You can view the metrics for a Queue on your account via the [Cloudflare dashboard](https://dash.cloudflare.com). Navigate to **Storage & Databases** > **Queues** > **your Queue** and under the **Metrics** tab you'll be able to view line charts describing the number of messages processed by final outcome, the number of messages in the backlog, and other important indicators.
The metrics displayed in the Cloudflare dashboard charts are all pulled from Cloudflare's GraphQL Analytics API. You can access the metrics programmatically.
The Queues metrics are split across three different nodes under `viewer` > `accounts`. Refer to [Explore the GraphQL schema](/analytics/graphql-api/getting-started/explore-graphql-schema/) to learn how to navigate a GraphQL schema and discover which data are available.
To learn more about the GraphQL Analytics API, refer to [GraphQL Analytics API](/analytics/graphql-api/).
## Write GraphQL queries
Examples of how to explore your Queues metrics.
### Get average Queue backlog over time period
```graphql
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
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
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
}
}
}
}
}
```
---
# 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.
---
# 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.
---
# Reference
URL: https://developers.cloudflare.com/queues/reference/
import { DirectoryListing } from "~/components"
<DirectoryListing />
---
# Tutorials
URL: https://developers.cloudflare.com/queues/tutorials/
import { ListTutorials } from "~/components"
<ListTutorials />
---
# API
URL: https://developers.cloudflare.com/r2/api/
import { DirectoryListing } from "~/components"
<DirectoryListing />
---
# 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>
---
# 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/s3/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 **Incremental 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 **Incremental 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) and 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
## 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.
---
# 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://4893d737c0b9e484dfc37ec392b5fa8a.r2.cloudflarestorage.com",
credentials: {
accessKeyId: "7dc27c125a22ad808cd01df8ec309d41",
secretAccessKey:
"1aa5c5b0c43defdb88f567487c071d17e234126133444770a706ae09336c57a4",
},
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/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`.
---
# 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/s3/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.
---
# 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.
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, [visit the public bucket documentation](/r2/buckets/public-buckets/).
- 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.
---
# 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/s3/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://4893d737c0b9e484dfc37ec392b5fa8a.r2.cloudflarestorage.com",
credentials: {
accessKeyId: "7dc27c125a22ad808cd01df8ec309d41",
secretAccessKey:
"1aa5c5b0c43defdb88f567487c071d17e234126133444770a706ae09336c57a4",
},
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://4893d737c0b9e484dfc37ec392b5fa8a.r2.cloudflarestorage.com",
credentials: {
accessKeyId: "7dc27c125a22ad808cd01df8ec309d41",
secretAccessKey:
"1aa5c5b0c43defdb88f567487c071d17e234126133444770a706ae09336c57a4",
},
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://4893d737c0b9e484dfc37ec392b5fa8a.r2.cloudflarestorage.com",
credentials: {
accessKeyId: "7dc27c125a22ad808cd01df8ec309d41",
secretAccessKey:
"1aa5c5b0c43defdb88f567487c071d17e234126133444770a706ae09336c57a4",
},
region: "auto",
});
// Delete lifecycle configuration for bucket
await client
.deleteBucketLifecycle({
Bucket: "bucketName",
})
.promise();
```
---
# 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 />
---
# 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 as a Cloudflare-managed subdomain under `https://r2.dev`.
To configure WAF custom rules, caching, access controls, or bot management for your bucket, you must do so through a custom domain.
Using a custom domain does not require enabling `r2.dev`.
:::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.
- [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-managed-public-access) 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/).
## 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/setup/account/account-security/zone-holds/#release-zone-holds) before adding the custom domain. A zone hold would prevent the custom subdomain from activating.
:::
### Restrictions
There is a restriction when using custom domains to access R2 buckets. The domain being used must belong to the same account as the R2 bucket.
## 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**.
3. Under **Public access** > **Custom Domains**, select **Connect Domain**.
4. Next to the domain you want to disable, select **...** and **Disable domain**.
5. The badge under **Access to Bucket** will update to **Not allowed**.
## Remove domain
Removing a domain will remove custom domain configuration that you have set up on the dashboard. Your bucket will still be publicly accessible.
To remove a domain:
1. In **R2**, select the bucket you want to modify.
2. On the bucket page, select **Settings**.
3. Under **Public access** > **Custom Domains**, select **Connect Domain**.
4. Next to the domain you want to disable, select **...** and **Remove domain**.
5. Select ‘Remove domain’ in the confirmation window. The CNAME record pointing to the domain will also be removed as part of this step. You can always add the domain again.
The domain is no longer connected to your bucket and will no longer appear in the connected domains list.
## Enable managed public access
When you enable managed public access for your bucket, the content of your bucket is available to the Internet through a Cloudflare-managed `r2.dev` subdomain.
:::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.
:::
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. In **Settings**, go to **Public Access**.
4. Under **R2.dev subdomain**, select **Allow Access**.
5. In **Allow Public Access?**, confirm your choice by typing ‘allow’ to confirm and select **Allow**.
6. You can now access the bucket and its objects using the Public Bucket URL.
You can review if your bucket is publicly accessible by going to your bucket and checking that **Public URL Access** states **Allowed**.
## Disable managed public access
Your bucket will not be exposed to the Internet as an `r2.dev` subdomain after you disable public access. If you have connected other domains, the bucket will remain accessible on 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 **Bucket Details** > **R2.dev subdomain**, select **Disallow Access**.
4. In **Disallow Public Access?**, type ‘disallow’ to confirm and select **Disallow**.
Your bucket and its objects can no longer be accessed using the Public Bucket URL.
---
# Storage classes
URL: https://developers.cloudflare.com/r2/buckets/storage-classes/
import { Badge } 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
<table>
<tbody>
<th style="width:25%">
Storage class
</th>
<th style="width:25%">
Minimum storage duration
</th>
<th style="width:25%">
Data retrieval fees (processing)
</th>
<th style="width:25%">
Egress fees (data transfer to Internet)
</th>
<tr>
<td>
Standard
</td>
<td>
None
</td>
<td>
None
</td>
<td>
None
</td>
</tr>
<tr>
<td>
Infrequent Access <inline-pill style="beta" />
</td>
<td>
30 days
</td>
<td>
Yes
</td>
<td>
None
</td>
</tr>
</tbody>
</table>
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/).
---
# 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);
}
},
};
```
---
# Expose an R2 bucket to the Internet via a Worker
URL: https://developers.cloudflare.com/r2/examples/demo-worker/
Below is an example Worker that exposes an R2 bucket to the Internet and demonstrates its functionality for storing and retrieving objects.
For a simpler guide level explanation of how to use R2 in a worker, refer to [use R2 in a Worker](/r2/api/workers/workers-api-usage/).
```ts
interface Env {
MY_BUCKET: R2Bucket
}
function objectNotFound(objectName: string): Response {
return new Response(`<html><body>R2 object "<b>${objectName}</b>" not found</body></html>`, {
status: 404,
headers: {
'content-type': 'text/html; charset=UTF-8'
}
})
}
export default {
async fetch(request, env): Promise<Response> {
const url = new URL(request.url)
const objectName = url.pathname.slice(1)
console.log(`${request.method} object ${objectName}: ${request.url}`)
if (request.method === 'GET' || request.method === 'HEAD') {
if (objectName === '') {
if (request.method == 'HEAD') {
return new Response(undefined, { status: 400 })
}
const options: R2ListOptions = {
prefix: url.searchParams.get('prefix') ?? undefined,
delimiter: url.searchParams.get('delimiter') ?? undefined,
cursor: url.searchParams.get('cursor') ?? undefined,
include: ['customMetadata', 'httpMetadata'],
}
console.log(JSON.stringify(options))
const listing = await env.MY_BUCKET.list(options)
return new Response(JSON.stringify(listing), {headers: {
'content-type': 'application/json; charset=UTF-8',
}})
}
if (request.method === 'GET') {
const object = await env.MY_BUCKET.get(objectName, {
range: request.headers,
onlyIf: request.headers,
})
if (object === null) {
return objectNotFound(objectName)
}
const headers = new Headers()
object.writeHttpMetadata(headers)
headers.set('etag', object.httpEtag)
if (object.range) {
headers.set("content-range", `bytes ${object.range.offset}-${object.range.end ?? object.size - 1}/${object.size}`)
}
const status = object.body ? (request.headers.get("range") !== null ? 206 : 200) : 304
return new Response(object.body, {
headers,
status
})
}
const object = await env.MY_BUCKET.head(objectName)
if (object === null) {
return objectNotFound(objectName)
}
const headers = new Headers()
object.writeHttpMetadata(headers)
headers.set('etag', object.httpEtag)
return new Response(null, {
headers,
})
}
if (request.method === 'PUT' || request.method == 'POST') {
const object = await env.MY_BUCKET.put(objectName, request.body, {
httpMetadata: request.headers,
})
return new Response(null, {
headers: {
'etag': object.httpEtag,
}
})
}
if (request.method === 'DELETE') {
await env.MY_BUCKET.delete(url.pathname.slice(1))
return new Response()
}
return new Response(`Unsupported method`, {
status: 400
})
}
} satisfies ExportedHandler<Env>;
```
---
# 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 } from "~/components";
<Render file="keys" />
<br />
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.
:::
:::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.
:::
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 `r2demo` provider:
```toml
[r2demo]
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/s3/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 r2demo:
# /
# ├── user-uploads
# │ └── foobar.png
# └── my-bucket-name
# ├── cat.png
# └── todos.txt
rclone tree r2demo: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 r2demo:user-uploads/
rclone tree r2demo:user-uploads
# /
# ├── foobar.png
# └── dog.txt
# Download dog.txt from the user-uploads bucket
rclone copy r2demo: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 r2demo: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 r2demo: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/setup/find-account-and-zone-ids/)
3. Populate `access_key` and `secret_key` with the corresponding [R2 API credentials](/r2/api/s3/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.
---
# 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.
---
# Delete objects
URL: https://developers.cloudflare.com/r2/objects/delete-objects/
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.
```
---
# Download objects
URL: https://developers.cloudflare.com/r2/objects/download-objects/
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).
---
# Objects
URL: https://developers.cloudflare.com/r2/objects/
import { DirectoryListing } from "~/components"
Objects are individual files or data that you store in an R2 bucket.
<DirectoryListing />
---
# Multipart upload
URL: https://developers.cloudflare.com/r2/objects/multipart-objects/
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
```
---
# Upload objects
URL: https://developers.cloudflare.com/r2/objects/upload-objects/
You can upload objects to your bucket from the Cloudflare dashboard or using the Wrangler.
## Upload objects via the Cloudflare dashboard
To upload objects to your bucket from 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. Select **Upload**.
4. 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.
## 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.
---
# Audit Logs
URL: https://developers.cloudflare.com/r2/platform/audit-logs/
[Audit logs](/fundamentals/setup/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/setup/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"
}
```
---
# Changelog
URL: https://developers.cloudflare.com/r2/platform/changelog/
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 />
---
# 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 |
<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 />
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
query {
viewer {
accounts(filter: { accountTag: $accountId }) {
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
query {
viewer {
accounts(filter: { accountTag: $accountId }) {
r2StorageAdaptiveGroups(
limit: 10000
filter: {
datetime_geq: $startDate
datetime_leq: $endDate
bucketName: $bucketName
}
orderBy: [datetime_DESC]
) {
max {
objectCount,
uploadCount,
payloadSize,
metadataSize
}
dimensions {
datetime
}
}
}
}
}
```
---
# 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://4893d737c0b9e484dfc37ec392b5fa8a.eu.r2.cloudflarestorage.com",
credentials: {
accessKeyId: "7dc27c125a22ad808cd01df8ec309d41",
secretAccessKey:
"1aa5c5b0c43defdb88f567487c071d17e234126133444770a706ae09336c57a4",
},
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/).
---
# 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.
:::
---
# Reference
URL: https://developers.cloudflare.com/r2/reference/
import { DirectoryListing } from "~/components"
<DirectoryListing />
---
# 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 `HeÌllo`, for example, are the same object in R2 but different objects in other storage providers. Although `Héllo` and `HeÌ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.
---
# 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/s3/tokens/) against R2 buckets.
---
# Tutorials
URL: https://developers.cloudflare.com/r2/tutorials/
import { GlossaryTooltip, ListTutorials } from "~/components"
View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with R2.
<ListTutorials />
---
# 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.
## 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.
### 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: "Hello World Worker",
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.
```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:
```sh
npm install 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.
## 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: "Hello World Worker",
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.
---
# 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": []
}
```
---
# 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
## 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.
---
# Edit videos
URL: https://developers.cloudflare.com/stream/edit-videos/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# 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.
---
# 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 isn't 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 [here](/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 |
---
# 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.
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/).
---
# 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.
---
# 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.
---
# 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.
---
# 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 }
```
---
# 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 title="GraphQL request"
query {
viewer {
accounts(filter:{
accountTag:"<ACCOUNT_ID>"
}) {
streamMinutesViewedAdaptiveGroups(
filter: {
date_geq: "2022-02-01"
date_lt: "2022-03-01"
}
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 title="GraphQL query"
query {
viewer {
accounts(filter:{
accountTag:"6c04ee5623f70a112c8f488e4c7a2409"
}) {
videoPlaybackEventsAdaptiveGroups(
filter: {
date_geq: "2020-09-01"
date_lt: "2020-09-25"
uid_gt:"5646153f8dea17f44d542a42e76cfd"
}
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
---
# 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 e.g. `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(
[...unescape(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('');
```
---
# 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 don't 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, go [here](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 isn't 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. (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.
---
# Resumable and large files (tus)
URL: https://developers.cloudflare.com/stream/uploading-videos/resumable-uploads/
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.
```sh title="Install tus-js-client"
npm install 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`.
:::
---
# 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**.
---
# 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.
---
# 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.
---
# 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/).
## 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": []
}
```
---
# 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
---
# 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.
---
# 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).
**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:** 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.
---
# 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_STORAGE_QUOTA_EXHAUSTED` – The account storage quota has been exceeded.
* `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.
```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,
}
```
---
# 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 e.g. `8m`, `5m2s`
* **`height`** (default `640`)
* **`width`** (default `640`)
* **`fit`** (default `crop`) to clarify what to do when requested height and width doesn't 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 e.g. `8m`, `5m2s`
* **`height`** (default `640`)
* **`width`** (default `640`)
* **`fit`** (default `crop`) to clarify what to do when requested height and width doesn't 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`)
---
# Play video
URL: https://developers.cloudflare.com/stream/viewing-videos/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# 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.
---
# 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:
- **Using the /token endpoint to generate signed tokens:** The simplest way to create a signed url token is by calling the /token endpoint. This is recommended for testing purposes or if you are generating less than 10,000 tokens per day.
- **Using an open-source library:** If you have tens of thousands of daily users and need to generate a high-volume of tokens without calling the /token endpoint _each time_, you can create tokens yourself. This way, you do not need to call a Stream endpoint 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:
```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: Generating signed tokens without calling the `/token` endpoint
If you are generating a high-volume of tokens, it is best to generate new tokens without needing 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' } }
```
## 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",
});
```
## 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: "Hello World Worker",
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 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/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: "Hello World Worker",
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 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 />
---
# Platform
URL: https://developers.cloudflare.com/vectorize/platform/
import { DirectoryListing } from "~/components"
<DirectoryListing />
---
# 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.
---
# 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
New Workers projects created via `npm create cloudflare@latest` automatically include the relevant TypeScript types for Vectorize.
Older projects, or non-Workers projects looking to use Vectorize's [REST API](https://developers.cloudflare.com/api/resources/vectorize/subresources/indexes/methods/list/) in a TypeScript project, should ensure `@cloudflare/workers-types` version `4.20230922.0` or later is installed.
---
# 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 be used to implement prefix searching on string metadata fields.
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.
Refer to the [RAG using Workers AI tutorial](/workers-ai/tutorials/build-a-retrieval-augmented-generation-ai/) to learn how to combine Workers AI and Vectorize for generative AI use-cases.
<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 } from "~/components"
View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with Vectorize.
<ListTutorials />
---
# 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 parameters to a Workflow
You can pass parameters to a Workflow in two 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.
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.
:::
```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(),
});
return Response.json({ result });
},
};
```
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
```
## 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"/>
---
# 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.
---
# Build with Workflows
URL: https://developers.cloudflare.com/workflows/build/
import { DirectoryListing } from "~/components"
<DirectoryListing />
---
# 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 an 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>
---
# 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)
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, 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<T>, step: WorkflowStep): Promise<T></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<T></code>
* <code>step.do(name: string, config?: WorkflowStepConfig, callback: (): RpcSerializable): Promise<T></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.
* <code>step.sleep(name: string, duration: WorkflowDuration): Promise<void></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 how Workflows are retried.
* <code>step.sleepUntil(name: string, timestamp: Date | number): Promise<void></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/).
:::
## 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 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 how Workflows are retried.
## Call Workflows from Workers
:::note[Workflows beta]
Workflows currently requires you to bind to a Workflow via the [Wrangler configuration file](/workers/wrangler/configuration/), and does not yet support bindings via the Workers dashboard.
:::
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>
## Workflow
:::note
Ensure you have `@cloudflare/workers-types` version `4.20241022.0` 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.
```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<WorkflowInstance></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(),
});
}
}
```
### get
Get a specific Workflow instance by ID.
* <code>get(id: string): Promise<WorkflowInstance></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<void></code>
### pause
Pause a running Workflow instance.
* <code>pause(): Promise<void></code>
### resume
Resume a paused Workflow instance.
* <code>resume(): Promise<void></code>
### restart
Restart a Workflow instance.
* <code>restart(): Promise<void></code>
### terminate
Terminate a Workflow instance.
* <code>terminate(): Promise<void></code>
### 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": {
"@cloudflare/workers-types": "^4.20241224.0",
"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 directory="workflows/examples/" />
---
# Pay cart and send invoice
URL: https://developers.cloudflare.com/workflows/examples/send-invoices/
import { TabItem, Tabs, WranglerConfig } 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": {
"@cloudflare/workers-types": "^4.20241022.0",
"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>
---
# 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" />
---
# CLI quick start
URL: https://developers.cloudflare.com/workflows/get-started/cli-quick-start/
import { Render, PackageManagers, WranglerConfig } from "~/components"
:::note
Workflows is in **public beta**, and any developer with a [free or paid Workers plan](/workers/platform/pricing/#workers) can start using Workflows immediately.
To learn more about Workflows and how it works, read [the beta announcement blog](https://blog.cloudflare.com/building-workflows-durable-execution-on-workers).
:::
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.
* `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"
:::note
Workflows is in **public beta**, and any developer with a [free or paid Workers plan](/workers/platform/pricing/#workers) can start using Workflows immediately.
To learn more about Workflows and how it works, read [the beta announcement blog](https://blog.cloudflare.com/building-workflows-durable-execution-on-workers).
:::
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).
---
# Get started
URL: https://developers.cloudflare.com/workflows/get-started/
import { DirectoryListing } from "~/components"
<DirectoryListing />
---
# Observability
URL: https://developers.cloudflare.com/workflows/observability/
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
{
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
{
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: "STEP_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
{
viewer {
accounts(filter: { accountTag: $accountTag }) {
workflowsAdaptive(
limit: 100
filter: {
datetime_geq: $datetimeStart
datetime_leq: $datetimeEnd
instanceId: $instanceId
}
orderBy: [datetime_ASC]
) {
datetime
eventType
workflowName
instanceId
stepName
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"
}
```
---
# Tutorials
URL: https://developers.cloudflare.com/workflows/tutorials/
import { GlossaryTooltip, ListTutorials } from "~/components";
:::note
[Explore our community-written tutorials contributed through the Developer Spotlight program.](/developer-spotlight/)
:::
View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with Workers.
<ListTutorials />
---
# 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 } 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 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 length of a Workflow ID [^4] | 64 characters | 64 characters |
| Maximum `step.sleep` duration | 365 days (1 year) [^1] | 365 days (1 year) [^1] |
| Maximum steps per Workflow [^5] | 1024 [^1] | 1024 [^1] |
| 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 [^1] |
| Maximum number of [queued instances](/workflows/observability/metrics-analytics/#event-types) | 10,000 [^1] | 100,000 [^1] |
| Retention limit for completed Workflow state | 3 days | 30 days [^2] |
| Maximum length of a Workflow ID [^4] | 64 characters | 64 characters |
[^1]: This limit will be reviewed and revised during the open beta for Workflows. Follow the [Workflows changelog](/workflows/reference/changelog/) for updates.
[^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
<Render file="limits_increase" product="workers" />
---
# 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 two 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.
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.
## 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) and requests (invocations) as Workers.
### 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.
---
# AI SDK
URL: https://developers.cloudflare.com/workers-ai/configuration/ai-sdk/
Workers AI can be used with the [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):
```bash
npm install 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/setup/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).
---
# Function calling
URL: https://developers.cloudflare.com/workers-ai/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/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/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: "",
tool_call: selected_tool.name,
},
{
role: "tool",
name: selected_tool.name,
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/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/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).
---
# Fine-tunes
URL: https://developers.cloudflare.com/workers-ai/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/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/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 the following models (must not be quantized):
* `@cf/meta-llama/llama-2-7b-chat-hf-lora`
* `@cf/mistral/mistral-7b-instruct-v0.2-lora`
* `@cf/google/gemma-2b-it-lora`
* `@cf/google/gemma-7b-it-lora`
* Adapter must be trained with rank `r <=8`. You can check the rank of a pre-trained LoRA adapter through the adapter's `config.json` file
* LoRA adapter file must be < 100MB
* 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/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/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"
});
```
---
# 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" />
---
# Get 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.
---
# CLI
URL: https://developers.cloudflare.com/workers-ai/get-started/workers-wrangler/
import { Render, PackageManagers, WranglerConfig } 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: "Hello World Worker",
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:
```typescript title="src/index.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>;
```
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.
---
# Guides
URL: https://developers.cloudflare.com/workers-ai/guides/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# Prompting
URL: https://developers.cloudflare.com/workers-ai/guides/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" />
---
# JSON Mode
URL: https://developers.cloudflare.com/workers-ai/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.
---
# Models
URL: https://developers.cloudflare.com/workers-ai/models/
import ModelCatalog from "~/pages/workers-ai/models/index.astro";
<ModelCatalog />
---
# 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/#text-classification)
* 2000 requests per minute
### [Text Embeddings](/workers-ai/models/#text-embeddings)
* 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/#text-generation)
* 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/#text-to-image)
* 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/#translation)
* 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.
## 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/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 |
## 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-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/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 |
---
# Build a Retrieval Augmented Generation (RAG) AI
URL: https://developers.cloudflare.com/workers-ai/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.
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: "Hello World Worker",
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`:
```sh
npm install 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:
```sh
npm install @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':
```sh
npm install @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/cloudflare-errors/troubleshooting-cloudflare-5xx-errors/#error-523-origin-is-unreachable) 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/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 --experimental"} />
### 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.
<Tabs>
<TabItem label="npm" icon="seti:npm">
```sh
npx wrangler r2 bucket create <BUCKET_NAME>
```
</TabItem>
<TabItem label="yarn" icon="seti:yarn">
```sh
yarn dlx wrangler r2 bucket create <BUCKET_NAME>
```
</TabItem>
<TabItem label="pnpm" icon="pnpm">
```sh
pnpm dlx wrangler r2 bucket create <BUCKET_NAME>
```
</TabItem>
</Tabs>
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.
<Tabs>
<TabItem label="npm" icon="seti:npm">
```sh
npx wrangler d1 create <DB_NAME>
```
</TabItem>
<TabItem label="yarn" icon="seti:yarn">
```sh
yarn dlx wrangler d1 create <DB_NAME>
```
</TabItem>
<TabItem label="pnpm" icon="pnpm">
```sh
pnpm dlx wrangler d1 create <DB_NAME>
```
</TabItem>
</Tabs>
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.
<Tabs>
<TabItem label="npm" icon="seti:npm">
```sh
npx wrangler d1 migrations create <DB_NAME> "create notes table"
```
</TabItem>
<TabItem label="yarn" icon="seti:yarn">
```sh
yarn dlx wrangler d1 migrations create <DB_NAME> "create notes table"
```
</TabItem>
<TabItem label="pnpm" icon="pnpm">
```sh
pnpm dlx wrangler d1 migrations create <DB_NAME> "create notes table"
```
</TabItem>
</Tabs>
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.
<Tabs>
<TabItem label="npm" icon="seti:npm">
```sh
npx wrangler d1 migrations apply <DB_NAME>
```
</TabItem>
<TabItem label="yarn" icon="seti:yarn">
```sh
yarn dlx wrangler d1 migrations apply <DB_NAME>
```
</TabItem>
<TabItem label="pnpm" icon="pnpm">
```sh
pnpm dlx wrangler d1 migrations apply <DB_NAME>
```
</TabItem>
</Tabs>
:::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).
---
# Build an interview practice tool with Workers AI
URL: https://developers.cloudflare.com/workers-ai/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/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/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()))
```
### 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"])
```
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
```
[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/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/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/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/fine-tunes/loras/#running-inference-with-loras).
---
# Choose the Right Text Generation Model
URL: https://developers.cloudflare.com/workers-ai/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/tutorials/
import { GlossaryTooltip, ListTutorials } from "~/components";
:::note
[Explore our community-written tutorials contributed through the Developer Spotlight program.](/developer-spotlight/)
:::
View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with Workers AI.
<ListTutorials />
---
# Llama 3.2 11B Vision Instruct model on Cloudflare Workers AI
URL: https://developers.cloudflare.com/workers-ai/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: "Hello World Worker",
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"
model = "@cf/meta/llama-3.2-11b-vision-instruct"
```
</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/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/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.
---
# 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`).
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 { WranglerConfig } 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.
Refer to the following examples to write your code:
- [Setting Cron Triggers](/workers/examples/cron-trigger/)
- [Multiple Cron Triggers](/workers/examples/multiple-cron-triggers/)
### 2. Update configuration
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]` table 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 # |
### 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
The recommended way of testing Cron Triggers is using Wrangler.
:::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.
:::
Test Cron Triggers using `Wrangler` by passing in the `--test-scheduled` flag to [`wrangler dev`](/workers/wrangler/commands/#dev). This will expose a `/__scheduled` 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=*+*+*+*+*"
```
## 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**.
:::note
You can only delete Cron Triggers using the Cloudflare dashboard (and not through your Wrangler file).
:::
## 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
Environment variables are a type of binding that allow you 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
Text and JSON values are defined 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>
`vars` is a non-inheritable key. [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.
To define environment variables for different environments, refer to the example below:
<WranglerConfig>
```toml
name = "my-worker-dev"
[env.staging.vars]
API_HOST = "staging.example.com"
API_ACCOUNT_ID = "staging_example_user"
SERVICE_X_DATA = { URL = "service-x-api.dev.example", MY_ID = 123 }
[env.production.vars]
API_HOST = "production.example.com"
API_ACCOUNT_ID = "production_example_user"
SERVICE_X_DATA = { URL = "service-x-api.prod.example", MY_ID = 456 }
```
</WranglerConfig>
For local development with `wrangler dev`, variables in the [Wrangler configuration file](/workers/wrangler/configuration/) are automatically overridden by any values defined in a `.dev.vars` file located in the root directory of your worker. This is useful for providing values you do not want to check in to source control.
```shell
API_HOST = "localhost:4000"
API_ACCOUNT_ID = "local_example_user"
```
Alternatively, you can specify per-environment values in the [Wrangler configuration file](/workers/wrangler/configuration/) and provide an `environment` value via the `env` flag when developing locally like so `wrangler dev --env=local`.
## 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/).
:::
<Render file="env_and_secrets" />
## Related resources
* Learn how to access environment variables in [ES modules syntax](/workers/reference/migrate-to-module-workers/) for an optimized experience.
---
# 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"
}
```
## 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/#1-html_handling) determines the redirects and rewrites of requests for HTML content.
* [not_found_handling](/workers/static-assets/routing/#2-not_found_handling) determines the response when a request does not match a static asset, and there is no Worker script.
* `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`.
* `usage_model` <Type text="string" /> <MetaInfo text="optional" />
* Usage model to apply to invocations, only allowed value is `standard`.
## 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>"
}
]
}
```
---
# 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/).
---
# 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/).
## 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-2) 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.
---
# 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.
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.
## 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.
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:
- Traditional hosted relational databases, including Postgres and MySQL.
- Serverless databases: Supabase, MongoDB Atlas, PlanetScale, FaunaDB, and Prisma.
- Cloudflare's own [D1](/d1/), a serverless SQL-based database.
| Database | Integration | Library or Driver | Connection Method |
| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| [Postgres](/workers/tutorials/postgres/) | - | [Postgres.js](https://github.com/porsager/postgres),[node-postgres](https://node-postgres.com/) | [Hyperdrive](/hyperdrive/) |
| [Postgres](/workers/tutorials/postgres/) | - | [deno-postgres](https://github.com/cloudflare/worker-template-postgres) | [TCP Socket](/workers/runtime-apis/tcp-sockets/) via database driver |
| [MySQL](/workers/tutorials/postgres/) | - | [deno-mysql](https://github.com/cloudflare/worker-template-mysql) | [TCP Socket](/workers/runtime-apis/tcp-sockets/) via database driver |
| [Fauna](https://docs.fauna.com/fauna/current/build/integration/cloudflare/) | [Yes](/workers/databases/native-integrations/fauna/) | [fauna](https://github.com/fauna/fauna-js) | API through client library |
| [PlanetScale](https://planetscale.com/blog/introducing-the-planetscale-serverless-driver-for-javascript) | [Yes](/workers/databases/native-integrations/planetscale/) | [@planetscale/database](https://github.com/planetscale/database-js) | API via client library |
| [Supabase](https://github.com/supabase/supabase/tree/master/examples/with-cloudflare-workers) | [Yes](/workers/databases/native-integrations/supabase/) | [@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) | No | [prisma](https://github.com/prisma/prisma) | API via client library |
| [Neon](https://blog.cloudflare.com/neon-postgres-database-from-workers/) | [Yes](/workers/databases/native-integrations/neon/) | [@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/) | No | API | GraphQL API via fetch() |
| [Upstash Redis](https://blog.cloudflare.com/cloudflare-workers-database-integration-with-upstash/) | [Yes](/workers/databases/native-integrations/upstash/) | [@upstash/redis](https://github.com/upstash/upstash-redis) | API via client library |
| [TiDB Cloud](https://docs.pingcap.com/tidbcloud/integrate-tidbcloud-with-cloudflare) | No | [@tidbcloud/serverless](https://github.com/tidbcloud/serverless-js) | API via client library |
:::note
If you do not see an integration listed or have an integration to add, complete and submit the [Cloudflare Developer Platform Integration form](https://forms.gle/iaUqLWE8aezSEhgd6).
:::
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.
## Connect to a database from a Worker
There are four ways to connect to a database from a Worker:
1. With [Hyperdrive](/hyperdrive/) (recommended), which dramatically speeds up accessing traditional databases. Hyperdrive currently supports PostgreSQL and PostgreSQL-compatible database providers.
2. [Database Integrations](/workers/databases/native-integrations/): Simplifies authentication by managing credentials on your behalf and includes support for PlanetScale, Neon and Supabase.
3. [TCP Socket API](/workers/runtime-apis/tcp-sockets): A direct TCP connection to a database. TCP is the de-facto standard protocol that many databases, such as PostgreSQL and MySQL, use for client connectivity.
4. HTTP- or WebSocket-based serverless drivers: Many hosted databases support a HTTP or WebSocket API to enable either clients to connect from environments that do not support TCP, or as their preferred connection protocol.
## 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 />
---
# Frameworks
URL: https://developers.cloudflare.com/workers/frameworks/
import {
Badge,
Description,
DirectoryListing,
InlineBadge,
Render,
TabItem,
Tabs,
PackageManagers,
Feature,
} from "~/components";
<Description>
Run front-end websites — static or dynamic — directly on Cloudflare's global
network.
</Description>
The following frameworks have experimental support for Cloudflare Workers and the new [<InlineBadge preset="beta" /> Workers Assets](/workers/static-assets/). They can be initialized with the [`create-cloudflare` CLI](/workers/get-started/guide/) using the `--experimental` flag.
<PackageManagers
type="create"
pkg="cloudflare@latest my-framework-app"
args={"--type=web-framework --experimental"}
/>
<DirectoryListing folder="workers/frameworks/framework-guides" />
:::note
**Static Assets for Workers is currently in open beta.**
If you are looking for a framework not on this list:
- It may be supported in [Cloudflare Pages](/pages/). Refer to [Pages Frameworks guides](/pages/framework-guides/) for a full list.
- Tell us which framework you would like to see supported on Workers in our [Cloudflare's Developer Discord](https://discord.gg/dqgZUwcD).
:::
---
# 103 Early Hints
URL: https://developers.cloudflare.com/workers/examples/103-early-hints/
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 js import Response, Headers
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 = Headers.new({"content-type": "text/css"}.items())
return Response.new(CSS, headers=headers)
else:
headers = Headers.new({"content-type": "text/html","link": "</test.css>; rel=preload; as=style"}.items())
return Response.new(HTML, headers=headers)
```
</TabItem> </Tabs>
---
# 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 js import Response, Headers, 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=/'
headers = Headers.new(headers.items())
return Response.new(res.body, headers=headers)
return fetch(urlunparse(url))
```
</TabItem> </Tabs>
---
# Aggregate requests
URL: https://developers.cloudflare.com/workers/examples/aggregate-requests/
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="Python" icon="seti:python">
```py
from js import Response, fetch, Headers, JSON, Promise
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 Promise.all([fetch(url1), fetch(url2)])
results = await Promise.all(map(lambda r: r.json(), responses))
headers = Headers.new({"content-type": "application/json;charset=UTF-8"}.items())
return Response.new(JSON.stringify(results), headers=headers)
```
</TabItem> </Tabs>
---
# Accessing the Cloudflare Object
URL: https://developers.cloudflare.com/workers/examples/accessing-the-cloudflare-object/
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="Python" icon="seti:python">
```py
import json
from js import Response, Headers, 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 = Headers.new({"content-type":"application/json"}.items())
return Response.new(JSON.stringify(data, None, 2), headers=headers)
```
</TabItem> </Tabs>
---
# Alter headers
URL: https://developers.cloudflare.com/workers/examples/alter-headers/
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 js import Response, fetch
async def on_fetch(request):
response = await fetch("https://example.com")
# Clone the response so that it's no longer immutable
new_response = Response.new(response.body, response)
# Add a custom header with a value
new_response.headers.append(
"x-workers-hello",
"Hello from Cloudflare Workers"
)
# Delete headers
new_response.headers.delete("x-header-to-delete")
new_response.headers.delete("x-header2-to-delete")
# Adjust the value for an existing header
new_response.headers.set("x-header-to-change", "NewValue")
return new_response
```
</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 js import Response, fetch
async def on_fetch(request):
PRESHARED_AUTH_HEADER_KEY = "X-Custom-PSK"
PRESHARED_AUTH_HEADER_VALUE = "mypresharedkey"
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 Response.new("Sorry, you have supplied an invalid key.", status=403);
```
</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> </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="Python" icon="seti:python">
```py
from js import Response, fetch
async def on_fetch(request):
tls_version = request.cf.tlsVersion
if tls_version not in ("TLSv1.2", "TLSv1.3"):
return Response.new("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="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 js import Response, fetch, URL
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 = URL.new(request.url)
location = redirect_map.get(url.pathname, None)
if location:
return Response.redirect(location, 301)
# If request not in map, return the original request
return fetch(request)
```
</TabItem> </Tabs>
---
# Using the Cache API
URL: https://developers.cloudflare.com/workers/examples/cache-api/
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> </Tabs>
---
# Cache POST requests
URL: https://developers.cloudflare.com/workers/examples/cache-post-request/
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> </Tabs>
---
# Cache Tags using Workers
URL: https://developers.cloudflare.com/workers/examples/cache-tags/
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") ? JSON.parse(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") ? JSON.parse(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="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/
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 js import Response, URL, fetch
async def on_fetch(request):
blocked_hostnames = ["nope.mywebsite.com", "bye.website.com"]
url = URL.new(request.url)
# Block on hostname
if url.hostname in blocked_hostnames:
return Response.new("Blocked Host", status=403)
# On paths ending in .doc or .xml
if re.search(r'\.(doc|xml)$', url.pathname):
return Response.new("Blocked Extension", status=403)
# On HTTP method
if "POST" in request.method:
return Response.new("Response for POST")
# On User Agent
user_agent = request.headers["User-Agent"] or ""
if "bot" in user_agent:
return Response.new("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.new("Block the IP 1.2.3.4", status=403)
# On ASN
if request.cf and request.cf.asn == 64512:
return Response.new("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> </Tabs>
---
# Cache using fetch
URL: https://developers.cloudflare.com/workers/examples/cache-using-fetch/
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="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> </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">
```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/
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="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/
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 js 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> </Tabs>
---
# Setting Cron Triggers
URL: https://developers.cloudflare.com/workers/examples/cron-trigger/
import { TabItem, Tabs, WranglerConfig } from "~/components";
<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">
```js
export default {
async scheduled(event, 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> </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` 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+*+*+*+*"
```
---
# Data loss prevention
URL: https://developers.cloudflare.com/workers/examples/data-loss-prevention/
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> </Tabs>
---
# Debugging logs
URL: https://developers.cloudflare.com/workers/examples/debugging-logs/
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> </Tabs>
---
# Cookie parsing
URL: https://developers.cloudflare.com/workers/examples/extract-cookie-value/
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 js 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.new(cookies[cookie_name].value)
return Response.new("No cookie with name: " + cookie_name)
```
</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.
:::
---
# Fetch HTML
URL: https://developers.cloudflare.com/workers/examples/fetch-html/
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> </Tabs>
---
# Geolocation: Weather application
URL: https://developers.cloudflare.com/workers/examples/geolocation-app-weather/
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="Python" icon="seti:python">
```py
from js import Response, Headers, 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 = Headers.new({"content-type": "text/html;charset=UTF-8"}.items())
return Response.new(html, headers=headers)
```
</TabItem> </Tabs>
---
# Fetch JSON
URL: https://developers.cloudflare.com/workers/examples/fetch-json/
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: 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: 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 js import Response, fetch, Headers, 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.stringify(await response.json()))
return (content_type, await response.text())
response = await fetch(url)
content_type, result = await gather_response(response)
headers = Headers.new({"content-type": content_type}.items())
return Response.new(result, headers=headers)
```
</TabItem> </Tabs>
---
# Geolocation: Hello World
URL: https://developers.cloudflare.com/workers/examples/geolocation-hello-world/
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 js import Response, Headers
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 = Headers.new({"content-type": "text/htmlcharset=UTF-8"}.items())
return Response.new(html, headers=headers)
```
</TabItem> </Tabs>
---
# Geolocation: Custom Styling
URL: https://developers.cloudflare.com/workers/examples/geolocation-custom-styling/
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> </Tabs>
---
# Hot-link protection
URL: https://developers.cloudflare.com/workers/examples/hot-link-protection/
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 js import Response, URL, fetch
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 URL.new(referer).hostname != URL.new(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> </Tabs>
---
# Custom Domain with Images
URL: https://developers.cloudflare.com/workers/examples/images-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="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";
:::note
[Explore our community-written tutorials contributed through the Developer Spotlight program.](/developer-spotlight/)
:::
Explore the following <GlossaryTooltip term="code example">examples</GlossaryTooltip> for Workers.
<ListExamples directory="workers/examples/" filters={["languages", "tags"]} />
---
# Modify request property
URL: https://developers.cloudflare.com/workers/examples/modify-request-property/
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> </Tabs>
---
# Logging headers to console
URL: https://developers.cloudflare.com/workers/examples/logging-headers/
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 js import Response
async def on_fetch(request):
print(dict(request.headers))
return Response.new('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> </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 response
URL: https://developers.cloudflare.com/workers/examples/modify-response/
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 js import Response, fetch, 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.new(original_response.body, status=500, statusText="some message", headers=original_response.headers)
# Change response body by adding the foo prop
original_body = await original_response.json()
original_body.foo = "bar"
response = Response.new(JSON.stringify(original_body), response)
# 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> </Tabs>
---
# Multiple Cron Triggers
URL: https://developers.cloudflare.com/workers/examples/multiple-cron-triggers/
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> </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` 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+*+*+*+*"
```
---
# Stream OpenAI API Responses
URL: https://developers.cloudflare.com/workers/examples/openai-sdk-streaming/
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/).
:::
```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>;
```
---
# Using timingSafeEqual
URL: https://developers.cloudflare.com/workers/examples/protect-against-timing-attacks/
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 js import Response, 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.new("Missing secret binding", status=500)
if len(auth_token) != len(secret):
return Response.new("Unauthorized", status=401)
if a.byteLength != b.byteLength:
return Response.new("Unauthorized", status=401)
encoder = TextEncoder.new()
a = encoder.encode(auth_token)
b = encoder.encode(secret)
if not crypto.subtle.timingSafeEqual(a, b):
return Response.new("Unauthorized", status=401)
return Response.new("Welcome!")
```
</TabItem> </Tabs>
---
# Post JSON
URL: https://developers.cloudflare.com/workers/examples/post-json/
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> </Tabs>
---
# Read POST
URL: https://developers.cloudflare.com/workers/examples/read-post/
import { TabItem, Tabs } from "~/components";
<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> </Tabs>
---
# Redirect
URL: https://developers.cloudflare.com/workers/examples/redirect/
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 js 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> </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 js import Response, URL
async def on_fetch(request):
base = "https://example.com"
statusCode = 301
url = URL.new(request.url)
destinationURL = f'{base}{url.pathname}{url.search}'
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> </Tabs>
---
# Respond with another site
URL: https://developers.cloudflare.com/workers/examples/respond-with-another-site/
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 js import Response, fetch, Headers
def on_fetch(request):
def method_not_allowed(request):
msg = f'Method {request.method} not allowed.'
headers = Headers.new({"Allow": "GET"}.items)
return Response.new(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 JSON
URL: https://developers.cloudflare.com/workers/examples/return-json/
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 js import Response, Headers
import json
def on_fetch(request):
data = json.dumps({"hello": "world"})
headers = Headers.new({"content-type": "application/json"}.items())
return Response.new(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> </Tabs>
---
# Return small HTML page
URL: https://developers.cloudflare.com/workers/examples/return-html/
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 js import Response, Headers
def on_fetch(request):
html = """<!DOCTYPE html>
<body>
<h1>Hello World</h1>
<p>This markup was generated by a Cloudflare Worker.</p>
</body>"""
headers = Headers.new({"content-type": "text/html;charset=UTF-8"}.items())
return Response.new(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>
</Tabs>
---
# Rewrite links
URL: https://developers.cloudflare.com/workers/examples/rewrite-links/
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> </Tabs>
---
# Sign requests
URL: https://developers.cloudflare.com/workers/examples/signing-requests/
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/#enable-nodejs-with-workers).
:::
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> </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/
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/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/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/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/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/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/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/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/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 js import Response, fetch, Headers
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/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/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/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/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 = Headers.new(res.headers)
# This sets the headers for HTML responses
if "text/html" in new_headers["Content-Type"]:
return Response.new(res.body, status=res.status, statusText=res.statusText, headers=new_headers)
for name in default_security_headers:
new_headers.set(name, default_security_headers[name])
for name in blocked_headers:
new_headers.delete(name)
tls = request.cf.tlsVersion
if not tls in ("TLSv1.2", "TLSv1.3"):
return Response.new("You need to use TLS version 1.2 or higher.", status=400)
return Response.new(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/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/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/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/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> </Tabs>
---
# Turnstile with Workers
URL: https://developers.cloudflare.com/workers/examples/turnstile-html-rewriter/
import { TabItem, Tabs } 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="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>
---
# 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/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> </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.
---
# 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](/learning-paths/get-started/account-setup/create-account/), if you have not already.
## Setup
To create a Workers application:
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to **Workers & Pages**.
3. Select **Create**.
4. Select a template or **Create Worker**.
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" />
## Next steps
To do more:
- Push your project to a GitHub or GitLab respoitory then [connect to builds](/workers/ci-cd/builds/#get-started) to enable automatic builds and deployments.
- 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: "Hello World Worker",
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/cloudflare-errors/troubleshooting-cloudflare-5xx-errors/#error-523-origin-is-unreachable) 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 respoitory 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/).
---
# Get 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.
### Getting started with Workers using a prompt <Badge text="Beta" variant="caution" size="small" />
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>
## 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.
---
# Quickstarts
URL: https://developers.cloudflare.com/workers/get-started/quickstarts/
import { LinkButton, WorkerStarter } from "~/components";
Quickstarts 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:
```sh
npm create cloudflare@latest <NEW_PROJECT_NAME> -- --template <GITHUB_REPO_URL>
```
- `new-project-name`
- A folder with this name will be created with your new project inside, pre-configured to [your Workers account](/workers/wrangler/configuration/).
- `template`
- This is the URL of the GitHub repo starter, as below. Refer to the [create-cloudflare documentation](/pages/get-started/c3/) for a full list of possible values.
## Example Projects
<WorkerStarter
title="Sentry"
repo="mhart/cf-sentry"
description="Log exceptions and errors in your Workers application to Sentry.io - an error tracking tool."
/>
<WorkerStarter
title="Image Color"
repo="xtuc/img-color-worker"
description="Retrieve the dominant color of a PNG or JPEG image."
/>
<WorkerStarter
title="Cloud Storage"
repo="conzorkingkong/cloud-storage"
description="Serve private Amazon Web Services (AWS) bucket files from a Worker script."
/>
<WorkerStarter
title="BinAST"
repo="xtuc/binast-cf-worker-template"
description="Serve a JavaScript Binary AST via a Cloudflare Worker."
/>
<WorkerStarter
title="Edge-Side Rendering"
repo="frandiox/vitessedge-template"
description="Use Vite to render pages on Cloudflare's global network with great DX. Includes i18n, markdown support and more."
/>
<WorkerStarter
title="REST API with Fauna"
repo="fauna-labs/fauna-workers"
description="Build a fast, globally distributed REST API using Cloudflare Workers and Fauna, the data API for modern applications."
/>
---
## Frameworks
<WorkerStarter
title="Apollo GraphQL Server"
repo="cloudflare/workers-graphql-server"
description="Lightning-fast, globally distributed Apollo GraphQL server, deployed on the Cloudflare global network using Cloudflare Workers."
/>
<WorkerStarter
title="GraphQL Yoga"
repo="the-guild-org/yoga-cloudflare-workers-template"
description="The most flexible, fastest, and lightest GraphQL server for all environments, Cloudflare Workers included."
/>
<WorkerStarter
title="Flareact"
repo="flareact/flareact"
description="Flareact is an edge-rendered React framework built for Cloudflare Workers. It features file-based page routing with dynamic page paths and edge-side data fetching APIs."
/>
<WorkerStarter
title="Sunder"
repo="sunderjs/sunder-worker-template"
description="Sunder is a minimal and unopinionated framework for Service Workers. This template uses Sunder, TypeScript, Miniflare, esbuild, Jest, and Sass, as well as Workers Sites for static assets."
/>
---
## 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>
---
# 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.
---
# 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 [unsupported](/workers/runtime-apis/fetch/). |
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` | Your Worker exceeded the size limit of XX MB (for more details see [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:
#### Worker exceeded the upload size limit
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.
To reduce the upload size of a Worker, you should consider removing unnecessary dependencies and/or using Workers KV, a D1 database or R2 to store configuration files, static assets and binary data instead of attempting to bundle them within your Worker code.
Another method to reduce a Worker's file size is to split its functionality across multiple Workers and connect them using [Service bindings](/workers/runtime-apis/bindings/service-bindings/).
#### 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.
A `responseStreamDisconnected` event `outcome` occurs when one end of the connection hangs up during the deferred proxying stage of a Worker request flow. This is regarded as an error for request metrics, and presents in logs as a non-error log entry. It commonly appears for longer lived connections such as WebSockets.
## Debug exceptions
After you have identified your Workers application is returning exceptions, use `wrangler tail` to inspect and fix the exceptions.
{/* <!-- TODO: include example --> */}
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 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">
```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">
```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 { 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/).
---
# Source maps and stack traces
URL: https://developers.cloudflare.com/workers/observability/source-maps/
import { Render, WranglerConfig } from "~/components"
<Render file="source-maps" product="workers" />
:::caution
Support for uploading source maps is available now in open beta. Minimum required Wrangler version: 3.46.0.
:::
## 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/integration-testing/#miniflares-api).
:::
## 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.
## 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.
---
# Platform
URL: https://developers.cloudflare.com/workers/platform/
import { DirectoryListing } from "~/components";
Pricing, limits and other information about the Workers platform.
<DirectoryListing />
---
# 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) |
---
# 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/cloudflare-errors/troubleshooting-cloudflare-1xxx-errors#error-1016-origin-dns-error).
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 } 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 |
<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 | 30 s 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. Most Workers requests consume less than a millisecond of CPU time. It is rare to find normally operating Workers that exceed the CPU time limit.
<Render file="isolate-cpu-flexibility" />
Using DevTools locally can help identify CPU intensive portions of your code. See the [CPU profiling with DevTools documentation](/workers/observability/dev-tools/cpu-usage/) to learn more.
You can also set a custom limit on the amount of CPU time that can be used during each invocation of your Worker. To do so, navigate to the Workers section in the Cloudflare dashboard. Select the specific Worker you wish to modify, then click on the "Settings" tab where you can 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/setup/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.
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. You should consider removing unnecessary dependencies and/or using [Workers KV](/kv/), a [D1 database](/d1/) or [R2](/r2/) to store configuration files, static assets and binary data instead of attempting to bundle them within your Worker code.
---
## 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.
<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 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 128 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
---
## 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 and Workers KV. Read more about the [Free plan limits](/workers/platform/limits/#worker-limits).
The Workers Paid plan includes Workers, Pages Functions, Workers KV, 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.
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 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 |
<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 CPU 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.
:::
:::note
Some Workers Enterprise customers maintain the ability to change usage models.
Usage models may be changed at the individual Worker 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 **Overview**, select your Worker > **Settings** > **Usage Model**.
To change your default account-wide usage model:
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In Account Home, select **Workers & Pages**.
3. Find **Usage Model** on the right-side menu > **Change**.
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/).
:::
## 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](#workers) and [Workers Paid](#workers) 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="durable_objects_pricing" />
:::note[Durable Objects billing examples]
For more information and [examples of Durable Objects billing](/durable-objects/platform/pricing/#durable-objects-billing-examples), refer to [Durable Objects Pricing](/durable-objects/platform/pricing/).
:::
## Durable Objects Storage API
<Render file="storage_api_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 } from "~/components";
Cloudflare Workers support a range of storage and database options for persisting different types of data across different use-cases, from key-value stores (like [Workers KV](/kv/)) through to SQL databases (such as [D1](/d1/)). This guide describes the use-cases suited to each storage option, as well as their performance and consistency properties.
:::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/).
:::
Available storage and persistency products include:
- [Workers KV](#workers-kv) for key-value storage.
- [R2](#r2) for object storage, including use-cases where S3 compatible storage is required.
- [Durable Objects](#durable-objects) for transactional, globally coordinated storage.
- [D1](#d1) as a relational, SQL-based database.
- [Queues](#queues) for job queueing, batching and inter-Service (Worker to Worker) communication.
- [Hyperdrive](/hyperdrive/) for connecting to and speeding up access to existing hosted and on-premises databases.
- [Analytics Engine](/analytics/analytics-engine/) for storing and querying (using SQL) time-series data and product metrics at scale.
- [Vectorize](/vectorize/) for vector search and storing embeddings from [Workers AI](/workers-ai/).
Applications built on the Workers platform may combine one or more storage components as they grow, scale or as requirements demand.
## Choose a storage product
<Render file="storage-products-table" product="workers" />
## Performance and consistency
The following table highlights the performance and consistency characteristics of the primary storage offerings available to Cloudflare Workers:
<table-wrap>
| Feature | Workers KV | R2 | Durable Objects | D1 |
| --------------------------- | ------------------------------------------------ | ------------------------------------- | -------------------------------- | --------------------------------------------------- |
| Maximum storage per account | Unlimited<sup>1</sup> | Unlimited<sup>2</sup> | 50 GiB | 250GiB <sup>3</sup> |
| Storage grouping name | Namespace | Bucket | Durable Object | Database |
| Maximum size per value | 25 MiB | 5 TiB per object | 128 KiB per value | 10 GiB per database <sup>4</sup> |
| Consistency model | Eventual: updates take up to 60s to be reflected | Strong (read-after-write)<sup>5</sup> | Serializable (with transactions) | Serializable (no replicas) / Causal (with replicas) |
| Supported APIs | Workers, HTTP/REST API | Workers, S3 compatible | Workers | Workers, HTTP/REST API |
</table-wrap>
<sup>1</sup> Free accounts are limited to 1 GiB of KV storage.
<sup>2</sup> Free accounts are limited to 10 GB of R2 storage.
<sup>3</sup> Free accounts are limited to 5 GiB of database storage.
<sup>4</sup> Free accounts are limited to 500 MiB per database.
<sup>5</sup> Refer to the [R2 documentation](/r2/reference/consistency/) for
more details on R2's consistency model.
<Render file="limits_increase" />
## 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.
- Per-object time-to-live (TTL).
- Distributed configuration.
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 existing 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/).
## 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/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" />
:::note[SQLite in Durable Objects Beta]
The new beta version of Durable Objects is available where each Durable Object has a private, embedded SQLite database. When deploying a new Durable Object class, users can opt-in to using SQL storage in order to access [Storage SQL API methods](/durable-objects/api/sql-storage/#exec). Otherwise, a Durable Object class has the standard, private key-value storage.
:::
<Render file="kv-vs-d1" product="kv" />
## D1 vs Hyperdrive
D1 is a standalone, serverless database that provides a SQL API, using SQLite's SQL semantics, to store and access your relational data.
Hyperdrive is a service that lets you connect to your existing, regional PostgreSQL databases and improves database performance by optimizing them for global, scalable data access from Workers.
- If you are building a new project on Workers or are considering migrating your data, use D1.
- If you are building a Workers project with an existing PostgreSQL database, use Hyperdrive.
:::note
You cannot use D1 with Hyperdrive.
However, D1 does not need to be used with Hyperdrive because it does not have slow connection setups which would benefit from Hyperdrive's connection pooling. D1 data can also be cached within Workers using the [Cache API](/workers/runtime-apis/cache/).
:::
---
# 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.
---
# 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, you must use the standard cache purge options. 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.
- Available to Enterprise Customers, [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/)
---
# 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.
---
# 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. [Durable Objects](/durable-objects/), [D1](/d1/), [Workers AI](/workers-ai/), [Vectorize](/vectorize/) and other bindings can only be used from Workers that use ES modules.
2. 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.
3. You can [gradually deploy changes to your Worker](/workers/configuration/versions-and-deployments/gradual-deployments/) when you use the ES modules format.
4. 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.
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');
});
```
---
# Reference
URL: https://developers.cloudflare.com/workers/reference/
import { DirectoryListing } from "~/components";
Conceptual knowledge about how Workers works.
<DirectoryListing />
---
# 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/setup/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/) |
---
# 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.
---
# 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.
## Limitations
The following limitations apply for Workers with static assets:
- 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.
- In local development, you cannot make [Service Binding RPC calls](/workers/runtime-apis/bindings/service-bindings/rpc/) to a Worker with static assets. This is a temporary limitation, we are working to remove it.
- Workers with assets cannot run on a [route or domain](/workers/configuration/routing/) with a path component. For example, `example.com/*` is an acceptable route, but `example.com/foo/*` is not. Wrangler and the Cloudflare dashboard will throw an error when you try and add a route with a path component.
## 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](/workers/static-assets/routing/#default-behavior)) will serve any static asset matching a request, while `run_worker_first = true` will unconditionally [invoke your Worker script](/workers/static-assets/routing/#invoking-worker-script-ahead-of-assets).
<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>
## `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/#routing-configuration) 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/#invoking-worker-script-ahead-of-assets) 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/#default-behavior).
---
# Workers vs. Pages (compatibility matrix)
URL: https://developers.cloudflare.com/workers/static-assets/compatibility-matrix/
import {
Badge,
Description,
FileTree,
InlineBadge,
Render,
TabItem,
Tabs,
} 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), to both Cloudflare [Workers](/workers/static-assets/) and [Pages](/pages/). The compatibility matrix below shows which features are available for each, to help you choose whether to build with Workers or 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).
We plan to bridge the gaps between Workers and Pages and provide ways to migrate your Pages projects to Workers.
**Legend** <br />
✅: Supported <br />
â³: Coming soon <br />
🟡: Unsupported, workaround available <br />
âŒ: Unsupported
| | Workers | Pages |
| ----------------------------------------------------------------------------------- | ------- | ------- |
| **Writing, Testing, and Deploying Code** | | |
| [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/local-development/) | ✅ | ✅ |
| [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](/pages/configuration/headers/) | 🟡 [^1] | ✅ |
| [Middleware](/workers/static-assets/binding/#run_worker_first) | ✅ [^2] | ✅ |
| [Redirects](/pages/configuration/redirects/) | 🟡 [^3] | ✅ |
| [Smart Placement](/workers/configuration/smart-placement/) | ✅ | ✅ |
| [Serve assets on a path](/workers/static-assets/routing/) | ✅ | ⌠|
| **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/) | ✅ | 🟡 [^4] |
| [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/) | ✅ | ✅ |
| [KV](/kv/) | ✅ | ✅ |
| [mTLS](/workers/runtime-apis/bindings/mtls/) | ✅ | ✅ |
| [Queue Producers](/queues/configuration/configure-queues/#producer) | ✅ | ✅ |
| [Queue Consumers](/queues/configuration/configure-queues/#consumer) | ✅ | ⌠|
| [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/) | ⌠| ✅ |
| [Custom Branch Aliases](/pages/how-to/custom-branch-aliases/) | ⌠| ✅ |
| **Pages Functions** | | |
| [File-based Routing](/pages/functions/routing/) | ⌠[^5] | ✅ |
| [Pages Plugins](/pages/functions/plugins/) | ⌠[^6] | ✅ |
| **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]: Similar to <sup>3</sup>, to customize the HTTP headers that are returned by static assets, you can use [Service bindings](/workers/runtime-apis/bindings/service-bindings/) to connect a Worker in front of the Worker with assets.
[^2]: 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.
[^3]: You can handle redirects by adding code to your Worker (a [community package](https://npmjs.com/package/redirects-in-workers) is available for `_redirects` support), or you can use [Bulk Redirects](/rules/url-forwarding/bulk-redirects/).
[^4]: 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.
[^5]: Workers [supports popular frameworks](/workers/frameworks/), many of which implement file-based routing.
[^6]: 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.
---
# Direct Uploads
URL: https://developers.cloudflare.com/workers/static-assets/direct-upload/
import {
Badge,
Description,
FileTree,
InlineBadge,
Render,
TabItem,
Tabs,
} 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" IconComponent={Icon}>
```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. Hashes of files that have been recently uploaded may not be returned in the API response; they do not need to be re-uploaded.
```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/static-assets/routing/#routing-configuration) 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
<Tabs> <TabItem label="TypeScript" icon="seti:typescript">
```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);
```
</TabItem> </Tabs>
---
# 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/frameworks/) that come with ready-to-use components, a pre-defined and structured architecture, and community support. View [framework specific guides](/workers/frameworks/) 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 --experimental"}
/>
<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "hello-world",
type: "Hello World - Assets-only",
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 --experimental"}
/>
<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "hello-world",
type: "Hello World - Worker with Assets",
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/).
:::
---
# Static Assets
URL: https://developers.cloudflare.com/workers/static-assets/
import {
Aside,
Badge,
Card,
CardGrid,
Details,
Description,
InlineBadge,
Icon,
DirectoryListing,
FileTree,
Render,
TabItem,
Tabs,
Feature,
LinkButton,
LinkCard,
Stream,
Flex,
WranglerConfig,
Steps,
} 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.
<LinkCard
title="Supported frameworks"
href="/workers/frameworks/"
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>
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 always be served — without running Worker code. If no matching asset is found and a Worker is configured, the request will be processed by the Worker instead.
- If no Worker is set up, the [`not_found_handling`](/workers/static-assets/routing/#2-not_found_handling-1) setting in your Wrangler configuration determines what happens next. By default, a `404 Not Found` response is returned.
- If a Worker is configured and a request does not match a static asset, the Worker will handle the request. The Worker can choose to pass the request to the asset binding (through `env.ASSETS.fetch()`), following the `not_found_handling` rules.
You can configure and override this default routing behaviour. For example, if you have a Single Page Application and want to serve `index.html` for all unmatched routes, you can set `not_found_handling = "single-page-application"`:
<WranglerConfig>
```toml
[assets]
directory = "./dist"
not_found_handling = "single-page-application"
```
</WranglerConfig>
If you want the Worker code to execute before serving an asset (for example, to protect an asset behind authentication), you can set `run_worker_first = true`.
<WranglerConfig>
```toml
[assets]
directory = "./dist"
run_worker_first = true
```
</WranglerConfig>
<LinkCard
title="Routing options"
href="/workers/static-assets/routing/#routing-configuration"
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
#### 1. Create a new Worker project
```sh
npm create cloudflare@latest -- my-dynamic-site
```
**For setup, select the following options**:
- For _What would you like to start with?_, choose `Framework`.
- For _Which framework would you like to use?_, choose `React`.
- 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).
After setting up the project, change the directory by running the following command:
```sh
cd my-dynamic-site
```
#### 2. Build project
Run the following command to build the project:
```sh
npm run build
```
We should now see a new directory `/dist` in our project, which contains the compiled assets:
<FileTree>
- package.json
- index.html
- ...
- dist Asset directory
- ... Compiled assets
- src
- ...
- ...
</FileTree>
In the next step, we use a Wrangler configuration file to allow Cloudflare to locate our compiled assets.
#### 3. Add a Wrangler configuration file (`wrangler.toml` or `wrangler.json`)
<WranglerConfig>
```toml
name = "my-spa"
compatibility_date = "2025-01-01"
[assets]
directory = "./dist"
```
</WranglerConfig>
**Notice the `[assets]` block**: here we have specified our directory where Cloudflare can find our compiled assets (`./dist`).
Our project structure should now look like this:
<FileTree>
- package.json
- index.html
- **wrangler.toml** Wrangler configuration
- ...
- dist Asset directory
- ... Compiled assets
- src
- ...
- ...
</FileTree>
#### 4. Deploy with Wrangler
```sh
npx wrangler deploy
```
Our project is now deployed on Workers! But we can take this even further, by adding an **API Worker**.
#### 5. Adjust our Wrangler configuration
Replace the file contents of our Wrangler configuration with the following:
<WranglerConfig>
```toml
name = "my-spa"
main = "src/api/index.js"
compatibility_date = "2025-01-01"
[assets]
directory = "./dist"
binding = "ASSETS"
not_found_handling = "single-page-application"
```
</WranglerConfig>
We have edited the Wrangler file in the following ways:
- Added `main = "src/api/index.js"` to tell Cloudflare where to find our Worker code.
- Added an `ASSETS` binding, which our Worker code can use to fetch and serve assets.
- Enabled routing for Single Page Applications, which ensures that unmatched routes (such as `/dashboard`) serve our `index.html`.
:::note
By default, Cloudflare serves a `404 Not Found` to unmatched routes. To have the frontend handle routing instead of the server, you must enable `not_found_handling = "single-page-application"`.
:::
#### 5. Create a new directory `/api`, and add an `index.js` file
Copy the contents below into the index.js file.
```js {13}
// api/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);
},
};
```
**Consider what this Worker does:**
- Our Worker receives a HTTP request and extracts the URL.
- If the request is for an API route (`/api/...`), it returns a JSON response.
- Otherwise, it serves static assets from our directory (`env.ASSETS`).
#### 6. 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. Replace the file contents with the following code:
```js {9,25, 33-47}
// 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;
```
Before deploying again, we need to rebuild our project:
```sh
npm run build
```
#### 7. Deploy with Wrangler
```sh
npx wrangler deploy
```
Now we can see a new button **Name from API**, and if you click the button, we can see our API response as **Cloudflare**!
## Learn more
<LinkCard
title="Supported frameworks"
href="/workers/frameworks/"
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."
/>
---
# Routing
URL: https://developers.cloudflare.com/workers/static-assets/routing/
import {
Badge,
Description,
FileTree,
InlineBadge,
Render,
TabItem,
Tabs,
WranglerConfig,
} from "~/components";
## Default behavior
By default, assets are served by attempting to match up the incoming request's pathname to a static asset. The structure and organization of files in your static asset directory, along with any routing configuration, determine the routing paths for your application. When a request invokes a Worker with assets:
1. If a request is found with a matching path to the current route requested then that asset will always be served.
In this example, request to `example.com/blog` serves the `blog.html` file.
2. If there is no Worker script, [`not_found_handling`](/workers/static-assets/routing/#2-not_found_handling) will be evaluated. By default, a null-body 404-status response will be served.
If a Worker is configured, and there are no assets that match the current route requested, the Worker will be invoked. The Worker can then "fall back" to `not_found_handling` asset behavior, by passing the incoming request through to the [asset binding](/workers/static-assets/binding/#runtime-api-reference).
In this example, a request to `example.com/api` doesn't match a static asset so the Worker is invoked.
## Invoking Worker Script Ahead of Assets
You may wish to run code before assets are served. This is often the case when implementing authentication, logging, personalization, internationalization, or other similar functions. [`run_worker_first`](/workers/static-assets/binding/#run_worker_first) is a configuration option available in [Wrangler configuration file](/workers/wrangler/configuration/) which controls this behavior. When enabled, `run_worker_first = true` will invoke your Worker's code, regardless of any assets that would have otherwise matched.
Take the following directory structure, [Wrangler configuration file](/workers/wrangler/configuration/), and user Worker code:
<FileTree>
- wrangler.json
- package.json
- public
- supersecret.txt
- src
- index.ts
</FileTree>
<WranglerConfig>
```toml title="wrangler.toml"
name = "my-worker"
compatibility_date = "2024-09-19"
main = "src/index.ts"
assets = { directory = "./public/", binding = "ASSETS", run_worker_first = true }
```
</WranglerConfig>
```js
export default {
async fetch(
request: Request,
env: Env,
ctx: ExecutionContext
): Promise<Response> {
const url = new URL(request.url);
if (url.pathname === "/supersecret.txt") {
const auth = request.headers.get("Authorization");
if (!auth) {
return new Response("Forbidden", {
status: 403,
statusText: "Forbidden",
headers: {
"Content-Type": "text/plain",
},
});
}
}
return await env.ASSETS.fetch(request);
},
};
```
In this example, any request will be routed to our user Worker, due to `run_worker_first` being enabled. As a result, any request being made `/supersecret.txt` without an `Authorization` header will result in a 403.
## Routing configuration
There are two options for asset serving that can be configured in the [Wrangler configuration file](/workers/wrangler/configuration/#assets):
#### 1. `html_handling`
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.
`html_handling` configuration 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.
#### 2. `not_found_handling`
In the event a request does not match a static asset, and there is no Worker script (or that Worker script calls `fetch()` on [the assets binding](/workers/static-assets/binding/)), `not_found_handling` determines how Cloudflare will construct a response.
It can be used to serve single-page applications (SPAs), or to serve custom 404 HTML pages.
If creating a SPA, place an `/index.html` in your asset directory. When `not_found_handling` is configured to `"single-page-application"`, this page will be served with a 200 response.
If you have custom 404 HTML pages, and configure `not_found_handling` to `"404-page"`, Cloudflare will recursively navigate up by pathname segment to serve the nearest `404.html` file. For example, you can have a `/404.html` and `/blog/404.html` file, and Cloudflare will serve the `/blog/404.html` file for requests to `/blog/not-found` and the `/404.html` file for requests to `/foo/bar`.
### Default configuration
#### 1. `html_handling`
`"auto-trailing-slash"` is the default mode if `html_handling` is not explicitly specified.
Take the following directory structure:
<FileTree>
- file.html
- folder
- index.html
</FileTree>
Based on the incoming requests, the following assets would be served:
| Incoming Request | Response | Asset Served |
| ------------------ | --------------- | ------------------ |
| /file | 200 | /file.html served |
| /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 | /folder/index.html |
| /folder/index | 307 to /folder/ | - |
| /folder/index.html | 307 to /folder/ | - |
#### 2. `not_found_handling`
`"none"` is the default mode if `not_found_handling` is not explicitly specified.
For all non-matching requests, Cloudflare will return a null-body 404-status response.
```
/not-found -> 404
/foo/path/doesnt/exist -> 404
```
### Alternate configuration options
Alternate configuration options are outlined on this page and can be specified in your project's [Wrangler configuration file](/workers/wrangler/configuration/#assets). If you're deploying using a [framework](/workers/frameworks/), these options will be defined by the framework provider.
Example Wrangler configuration file:
<WranglerConfig>
```toml title="wrangler.toml"
assets = { directory = "./public", binding = "ASSETS", html_handling = "force-trailing-slash", not_found_handling = "404-page" }
```
</WranglerConfig>
#### `html_handling = "auto-trailing-slash" | "force-trailing-slash" | "drop-trailing-slash" | "none"`
Take the following directory structure:
<FileTree>
- file.html
- folder
- index.html
</FileTree>
**`html_handling: "auto-trailing-slash"`**
Based on the incoming requests, the following assets would be served:
| Incoming Request | Response | Asset Served |
| ------------------ | --------------- | ------------------ |
| /file | 200 | /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 | /folder/index.html |
| /folder/index | 307 to /folder | - |
| /folder/index.html | 307 to /folder | - |
**`html_handling: "force-trailing-slash"`**
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 | /file.html |
| /file/index | 307 to /file/ | - |
| /file/index.html | 307 to /file/ | - |
| /folder | 307 to /folder/ | - |
| /folder.html | 307 to /folder/ | - |
| /folder/ | 200 | /folder/index.html |
| /folder/index | 307 to /folder/ | - |
| /folder/index.html | 307 to /folder/ | - |
**`html_handling: "drop-trailing-slash"`**
Based on the incoming requests, the following assets would be served:
| Incoming Request | Response | Asset Served |
| ------------------ | -------------- | ------------------ |
| /file | 200 | /file.html |
| /file.html | 307 to /file | - |
| /file/ | 307 to /file | - |
| /file/index | 307 to /file | - |
| /file/index.html | 307 to /file | - |
| /folder | 200 | /folder/index.html |
| /folder.html | 307 to /folder | - |
| /folder/ | 307 to /folder | - |
| /folder/index | 307 to /folder | - |
| /folder/index.html | 307 to /folder | - |
**`html_handling: "none"`**
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 | /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 | /folder/index.html |
#### `not_found_handling = "404-page" | "single-page-application" | "none"`
Take the following directory structure:
<FileTree>
- 404.html
- index.html
- folder
- 404.html
</FileTree>
**`not_found_handling: "none"`**
```
/not-found -> 404
/folder/doesnt/exist -> 404
```
**`not_found_handling: "404-page"`**
```
/not-found -> 404 /404.html
/folder/doesnt/exist -> 404 /folder/404.html
```
**`not_found_handling: "single-page-application"`**
```
/not-found -> 200 /index.html
/folder/doesnt/exist -> 200 /index.html
```
## Serving assets from a custom path
:::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.
{/* prettier-ignore */}
<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. 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).
```
---
# 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);
```
***
## 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 (Enterprise only).
* `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/)
---
# 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');
},
};
```
---
# 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).
---
# 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.
---
# 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/).
:::
## Syntax
<Tabs> <TabItem label="Module Worker" icon="seti:javascript">
```js null {3-7}
export default {
async scheduled(event, env, ctx) {
return await fetch("https://example.com", {
headers: {
"X-Source": "Cloudflare-Workers",
},
});
},
};
```
</TabItem> <TabItem label="Service Worker" icon="seti:javascript">
```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> </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/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/)
---
# 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 } 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/Methods) are supported, except for [`CONNECT`](https://developer.mozilla.org/en-US/docs/Web/HTTP/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`.
#### 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 [`@cloudflare/workers-types`](https://www.npmjs.com/package/@cloudflare/workers-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, which is currently only available to Enterprise zones. If this option is used in a non-Enterprise zone, the additional headers will not be appended.
* `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`.
* `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`.
* `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/)
---
# 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)
---
# 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');
```
---
# 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 for unit testing individual functions within your Worker. 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.
<LinkButton href="/workers/testing/vitest-integration/get-started/write-your-first-test/">
Write your first test
</LinkButton>
## Testing comparison matrix
| Feature | [Vitest integration](/workers/testing/vitest-integration) | [`unstable_startWorker()`](/workers/wrangler/api/#unstable_startworker) | [Miniflare's API](/workers/testing/miniflare) |
| ------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------- |
| Unit testing | ✅ | ⌠| ⌠|
| Integration testing | ✅ | ✅ | ✅ |
| Loading [Wrangler configuration files](/workers/wrangler/configuration/) | ✅ | ✅ | ⌠|
| 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" />
---
# Integration testing
URL: https://developers.cloudflare.com/workers/testing/integration-testing/
import { Render } from "~/components";
import { LinkButton } from "@astrojs/starlight/components";
Integration tests test multiple units of your Worker together by sending HTTP requests to your Worker and asserting on the HTTP responses. As an example, consider the following Worker:
```js
export function add(a, b) {
return a + b;
}
export default {
async fetch(request) {
const url = new URL(request.url);
const a = parseInt(url.searchParams.get("a"));
const b = parseInt(url.searchParams.get("b"));
return new Response(add(a, b));
},
};
```
An integration test for this Worker might look like the following example:
```js
// Start Worker HTTP server on port 8787 running `index.mjs` then...
const response = await fetch("http://localhost:8787/?a=1&b=2");
assert((await response.text()) === "3");
```
In the above example, instead of importing the `add` function as a [unit test](/workers/testing/unit-testing/) would do, you make a direct call to the endpoint, testing that the Worker responds at the endpoint with the appropriate response.
## Vitest integration
The recommended way to write integration tests for your Workers is by using [the Workers Vitest integration](/workers/testing/vitest-integration/get-started/). Vitest can be configured to run integrations against a single Worker or multiple Workers.
### Testing via `SELF`
If testing a single Worker, you can use the `SELF` fetcher provided by the [`cloudflare:test` API](/workers/testing/vitest-integration/test-apis/).
```js
import { SELF } from "cloudflare:test";
it("dispatches fetch event", async () => {
const response = await SELF.fetch("https://example.com");
expect(await response.text()).toMatchInlineSnapshot(...);
});
```
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 same subtly different module resolution behavior provided by Vite.
Usually this is not a problem, but if you would like to run your Worker in a fresh environment that is as close to production as possible, using an auxiliary Worker may be a good idea. Auxiliary Workers have some developer experience (DX) limitations.
### Testing via auxiliary Workers
It is also possible to configure Workers for integration testing via `vitest.config.ts`. An [example `vitest.config.ts` configuration file](https://github.com/cloudflare/workers-sdk/blob/main/fixtures/vitest-pool-workers-examples/basics-integration-auxiliary/vitest.config.ts) on GitHub.
The Worker can then be referenced like the following example:
```js
import { env } from "cloudflare:test";
import { expect, it } from "vitest";
it("dispatches fetch event", async () => {
const response = await env.WORKER.fetch("http://example.com");
expect(await response.text()).toBe("👋");
});
```
Instead of running the Worker-under-test in the same Worker as the test runner like `SELF`, this example defines the Worker-under-test as an _auxiliary_ Worker. This means the Worker runs in a separate isolate to the test runner, with a different global scope. The Worker-under-test runs in an environment closer to production, but Vite transformations and hot-module-reloading aren't applied to the Worker—you must compile your TypeScript to JavaScript beforehand.
Auxiliary Workers cannot be configured from Wrangler files. You must use Miniflare [`WorkerOptions`](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare#interface-workeroptions) in `vitest.config.ts`.
:::note
This method is less recommended than `SELF` for integration tests because of its developer experience. However, it can be useful when you are testing multiple Workers. You can define multiple Workers by different names in `vitest.config.ts` and reference them via `env`.
:::
## [Wrangler's `unstable_startWorker()` API](/workers/wrangler/api/#unstable_startworker)
:::caution
`unstable_startWorker()` is an experimental API subject to breaking changes.
:::
If you do not want to use Vitest and would like to write integration tests for a single Worker, 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.
```js
import assert from "node:assert";
import { unstable_startWorker } from "wrangler";
const worker = await unstable_startWorker({ config: "wrangler.json" });
try {
const response = await worker.fetch("/?a=1&b=2");
assert.strictEqual(await response.text(), "3");
} finally {
await worker.dispose();
}
```
## [Miniflare's API](/workers/testing/miniflare/writing-tests/)
If you would like to write integration tests for multiple Workers, need direct access to [bindings](/workers/runtime-apis/bindings/) outside your Worker in tests, or have another advanced use case, consider using [Miniflare's API](/workers/testing/miniflare) directly. Miniflare is the foundation for the other testing tools on this page, exposing a JavaScript API for the [`workerd` runtime](https://github.com/cloudflare/workerd) and local simulators for the other Developer Platform products. Unlike `unstable_startWorker()`, Miniflare does not automatically load options from your [Wrangler configuration file](/workers/wrangler/configuration/). Refer to the [Writing tests](/workers/testing/miniflare/writing-tests/) page for an example of how to use Miniflare together with `node:test`.
```js
import assert from "node:assert";
import { Miniflare } from "miniflare";
const mf = new Miniflare({
modules: true,
scriptPath: "./index.mjs",
});
try {
const response = await mf.dispatchFetch("http://example.com/?a=1&b=2");
assert.strictEqual(await response.text(), "3");
} finally {
await mf.dispose();
}
```
:::note
If you have been using the test environments from Miniflare 2 for integration testing and want to migrate to Cloudflare's Vitest integration, refer to the [Migrate from Miniflare 2 migration guide](/workers/testing/vitest-integration/get-started/migrate-from-miniflare-2/) for more information.
:::
<Render file="testing-pages-functions" product="workers" />
## Related Resources
- [Recipes](/workers/testing/vitest-integration/recipes/) - Example integration tests for Workers using the Workers Vitest integration.
---
# Tutorials
URL: https://developers.cloudflare.com/workers/tutorials/
import { GlossaryTooltip, ListTutorials } from "~/components";
:::note
[Explore our community-written tutorials contributed through the Developer Spotlight program.](/developer-spotlight/)
:::
View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with Workers.
<ListTutorials />
---
# Unit testing
URL: https://developers.cloudflare.com/workers/testing/unit-testing/
import { Render } from "~/components"
In a Workers context, a unit test imports and directly calls functions from your Worker. After calling the functions, the unit test then asserts on the functions' return values. For example, consider you have the following Worker:
```js
export function add(a, b) {
return a + b;
}
export default {
async fetch(request) {
const url = new URL(request.url);
const a = parseInt(url.searchParams.get("a"));
const b = parseInt(url.searchParams.get("b"));
return new Response(add(a, b));
}
}
```
An example unit test for the above Worker may look like the following:
```js
import { add } from "./index.mjs";
assert(add(1, 2) === 3);
```
This test only verifies that the `add` function is returning the correct value, but does not test the Worker itself like an [integration test](/workers/testing/integration-testing) would.
## Vitest integration
The recommended way to unit test your Workers is by using the Workers Vitest integration. For more information on features, as well as installation and setup instructions, refer to the [Vitest integration Get Started guide](/workers/testing/vitest-integration/get-started/).
<Render file="testing-pages-functions" product="workers" />
## Related Resources
* [Recipes](/workers/testing/vitest-integration/recipes/) - Examples of unit tests using the Workers Vitest integration.
---
# API
URL: https://developers.cloudflare.com/workers/wrangler/api/
import { Render, TabItem, Tabs, Type, MetaInfo, WranglerConfig } 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/get-started/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 sub directory 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: "./my-directory/v3"`.
### 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/)
- [Durable Object bindings](/durable-objects/api/)
- To use a Durable Object binding with `getPlatformProxy`, always [specify a `script_name`](/workers/wrangler/configuration/#durable-objects) and have the target Worker run in a separate terminal via [`wrangler dev`](/workers/wrangler/commands/#dev).
For example, you might have the following file read by `getPlatformProxy`.
<WranglerConfig>
```toml
[[durable_objects.bindings]]
name = "MyDurableObject"
class_name = "MyDurableObject"
script_name = "my-worker"
```
</WranglerConfig>
In order for this binding to be successfully proxied by `getPlatformProxy`, a worker named `my-worker`
with a Durable Object declaration using the same `class_name` of `"MyDurableObject"` must be run
separately via `wrangler dev`.
- [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" />
---
# 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.
:::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 } 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.
- [`generate`](#generate) - Create a Wrangler project using an existing [Workers template](https://github.com/cloudflare/worker-template).
- [`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.
- [`publish`](#publish) - Publish your Worker to Cloudflare.
- [`delete`](#delete-2) - 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`](#secretbulk) - Manage multiple secret variables for a Worker.
- [`workflows`](#workflows) - Manage and configure Workflows.
- [`tail`](#tail) - Start a session to livestream logs from a deployed Worker.
- [`pages`](#pages) - Configure Cloudflare Pages.
- [`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.
:::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.
<Tabs> <TabItem label="npm">
```sh
npx wrangler <COMMAND> <SUBCOMMAND> [PARAMETERS] [OPTIONS]
```
</TabItem> <TabItem label="yarn">
```sh
yarn wrangler <COMMAND> <SUBCOMMAND> [PARAMETERS] [OPTIONS]
```
</TabItem> <TabItem label="pnpm">
```sh
pnpm wrangler <COMMAND> <SUBCOMMAND> [PARAMETERS] [OPTIONS]
```
</TabItem> </Tabs>
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:
<Tabs> <TabItem label="npm">
```sh
npm run deploy
```
</TabItem> <TabItem label="yarn">
```sh
yarn run deploy
```
</TabItem> <TabItem label="pnpm">
```sh
pnpm run deploy
```
</TabItem> </Tabs>
---
## `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" />
---
## `generate`
:::note
This command has been deprecated as of [Wrangler v3](/workers/wrangler/migration/update-v2-to-v3/) and will be removed in a future version.
:::
Create a new project using an existing [Workers template](https://github.com/cloudflare/workers-sdk/tree/main/templates/worker).
```txt
wrangler generate [<NAME>] [TEMPLATE]
```
- `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/).
- `TEMPLATE` <Type text="string" /> <MetaInfo text="optional" />
- The URL of a GitHub template, with a default [worker-template](https://github.com/cloudflare/worker-template). Browse a list of available templates on the [cloudflare/workers-sdk](https://github.com/cloudflare/workers-sdk/tree/main/templates#usage) repository.
<Render file="wrangler-commands/global-flags" 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.
### `create`
Creates a new vector index, and provides the binding and name that you will put in your Wrangler file.
```sh
npx wrangler vectorize create <INDEX_NAME> [--dimensions=<NUM_DIMENSIONS>] [--metric=<DISTANCE_METRIC>] [--description=<DESCRIPTION>]
```
- `INDEX_NAME` <Type text="string" /> <MetaInfo text="required" />
- The name of the new index to create. Must be unique for an account and cannot be changed after creation.
- `--dimensions` <Type text="number" /> <MetaInfo text="required" />
- The vector dimension width to configure the index for. Cannot be changed after creation.
- `--metric` <Type text="string" /> <MetaInfo text="required" />
- The distance metric to use for calculating vector distance. Must be one of `cosine`, `euclidean`, or `dot-product`.
- `--description` <Type text="string" /> <MetaInfo text="optional" />
- A description for your index.
- `--deprecated-v1` <Type text="boolean" /> <MetaInfo text="optional" />
- Create a legacy Vectorize index. Please note that legacy Vectorize indexes are on a [deprecation path](/vectorize/reference/transition-vectorize-legacy).
<Render file="wrangler-commands/global-flags" product="workers" />
### `list`
List all Vectorize indexes in your account, including the configured dimensions and distance metric.
```sh
npx wrangler vectorize list
```
- `--deprecated-v1` <Type text="boolean" /> <MetaInfo text="optional" />
- List legacy Vectorize indexes. Please note that legacy Vectorize indexes are on a [deprecation path](/vectorize/reference/transition-vectorize-legacy).
<Render file="wrangler-commands/global-flags" product="workers" />
### `get`
Get details about an individual index, including its configuration.
```sh
npx wrangler vectorize get <INDEX_NAME>
```
- `INDEX_NAME` <Type text="string" /> <MetaInfo text="required" />
- The name of the index to fetch details for.
- `--deprecated-v1` <Type text="boolean" /> <MetaInfo text="optional" />
- Get a legacy Vectorize index. Please note that legacy Vectorize indexes are on a [deprecation path](/vectorize/reference/transition-vectorize-legacy).
<Render file="wrangler-commands/global-flags" product="workers" />
### `info`
Get some additional information about an individual index, including the vector count and details about the last processed mutation.
```sh
npx wrangler vectorize info <INDEX_NAME>
```
- `INDEX_NAME` <Type text="string" /> <MetaInfo text="required" />
- The name of the index to fetch details for.
<Render file="wrangler-commands/global-flags" product="workers" />
### `delete`
Delete a Vectorize index.
```sh
npx wrangler vectorize delete <INDEX_NAME> [OPTIONS]
```
- `INDEX_NAME` <Type text="string" /> <MetaInfo text="required" />
- The name of the Vectorize index to delete.
- `--force` <Type text="boolean" /> <MetaInfo text="optional" />
- Skip confirmation when deleting the index (Note: This is not a recoverable operation).
- `--deprecated-v1` <Type text="boolean" /> <MetaInfo text="optional" />
- Delete a legacy Vectorize index. Please note that legacy Vectorize indexes are on a [deprecation path](/vectorize/reference/transition-vectorize-legacy).
<Render file="wrangler-commands/global-flags" product="workers" />
### `insert`
Insert vectors into an index.
```sh
npx wrangler vectorize insert <INDEX_NAME> [OPTIONS]
```
- `INDEX_NAME` <Type text="string" /> <MetaInfo text="required" />
- The name of the Vectorize index to upsert vectors in.
- `--file` <Type text="string" /> <MetaInfo text="required" />
- A file containing the vectors to insert in newline-delimited JSON (JSON) format.
- `--batch-size` <Type text="number" /> <MetaInfo text="optional" />
- The number of vectors to insert at a time (default: `1000`).
- `--deprecated-v1` <Type text="boolean" /> <MetaInfo text="optional" />
- Insert into a legacy Vectorize index. Please note that legacy Vectorize indexes are on a [deprecation path](/vectorize/reference/transition-vectorize-legacy).
<Render file="wrangler-commands/global-flags" product="workers" />
### `upsert`
Upsert vectors into an index. Existing vectors in the index would be overwritten.
```sh
npx wrangler vectorize upsert <INDEX_NAME> [OPTIONS]
```
- `INDEX_NAME` <Type text="string" /> <MetaInfo text="required" />
- The name of the Vectorize index to upsert vectors in.
- `--file` <Type text="string" /> <MetaInfo text="required" />
- A file containing the vectors to insert in newline-delimited JSON (JSON) format.
- `--batch-size` <Type text="number" /> <MetaInfo text="optional" />
- The number of vectors to insert at a time (default: `5000`).
<Render file="wrangler-commands/global-flags" product="workers" />
### `query`
Query a Vectorize index for similar vectors.
```sh
npx wrangler vectorize query <INDEX_NAME> [OPTIONS]
```
- `INDEX_NAME` <Type text="string" /> <MetaInfo text="required" />
- The name of the Vectorize index to query.
- `--vector` <Type text="array" /> <MetaInfo text="optional" />
- Vector against which the Vectorize index is queried. Either this or the `vector-id` param must be provided.
- `--vector-id` <Type text="string" /> <MetaInfo text="optional" />
- Identifier for a vector that is already present in the index against which the index is queried. Either this or the `vector` param must be provided.
- `--top-k` <Type text="number" /> <MetaInfo text="optional" />
- The number of vectors to query (default: `5`).
- `--return-values` <Type text="boolean" /> <MetaInfo text="optional" />
- Enable to return vector values in the response (default: `false`).
- `--return-metadata` <Type text="string" /> <MetaInfo text="optional" />
- Enable to return vector metadata in the response. Must be one of `none`, `indexed`, or `all` (default: `none`).
- `--namespace` <Type text="string" /> <MetaInfo text="optional" />
- Query response to only include vectors from this namespace.
- `--filter` <Type text="string" /> <MetaInfo text="optional" />
- Filter vectors based on this metadata filter. Example: `'{ 'p1': 'abc', 'p2': { '$ne': true }, 'p3': 10, 'p4': false, 'nested.p5': 'abcd' }'`
<Render file="wrangler-commands/global-flags" product="workers" />
### `get-vectors`
Fetch vectors from a Vectorize index using the provided ids.
```sh
npx wrangler vectorize get-vectors <INDEX_NAME> [OPTIONS]
```
- `INDEX_NAME` <Type text="string" /> <MetaInfo text="required" />
- The name of the Vectorize index from which vectors need to be fetched.
- `--ids` <Type text="array" /> <MetaInfo text="required" />
- List of ids for which vectors must be fetched.
<Render file="wrangler-commands/global-flags" product="workers" />
### `delete-vectors`
Delete vectors in a Vectorize index using the provided ids.
```sh
npx wrangler vectorize delete-vectors <INDEX_NAME> [OPTIONS]
```
- `INDEX_NAME` <Type text="string" /> <MetaInfo text="required" />
- The name of the Vectorize index from which vectors need to be deleted.
- `--ids` <Type text="array" /> <MetaInfo text="required" />
- List of ids corresponding to the vectors that must be deleted.
<Render file="wrangler-commands/global-flags" product="workers" />
### `create-metadata-index`
Enable metadata filtering on the specified property.
```sh
npx wrangler vectorize create-metadata-index <INDEX_NAME> [OPTIONS]
```
- `INDEX_NAME` <Type text="string" /> <MetaInfo text="required" />
- The name of the Vectorize index for which metadata index needs to be created.
- `--property-name` <Type text="string" /> <MetaInfo text="required" />
- Metadata property for which metadata filtering should be enabled.
- `--type` <Type text="string" /> <MetaInfo text="required" />
- Data type of the property. Must be one of `string`, `number`, or `boolean`.
<Render file="wrangler-commands/global-flags" product="workers" />
### `list-metadata-index`
List metadata properties on which metadata filtering is enabled.
```sh
npx wrangler vectorize list-metadata-index <INDEX_NAME> [OPTIONS]
```
- `INDEX_NAME` <Type text="string" /> <MetaInfo text="required" />
- The name of the Vectorize index for which metadata indexes needs to be fetched.
<Render file="wrangler-commands/global-flags" product="workers" />
### `delete-metadata-index`
Disable metadata filtering on the specified property.
```sh
npx wrangler vectorize delete-metadata-index <INDEX_NAME> [OPTIONS]
```
- `INDEX_NAME` <Type text="string" /> <MetaInfo text="required" />
- The name of the Vectorize index for which metadata index needs to be disabled.
- `--property-name` <Type text="string" /> <MetaInfo text="required" />
- Metadata property for which metadata filtering should be disabled.
<Render file="wrangler-commands/global-flags" 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.
:::
:::caution
As of Wrangler v3.2.0, `wrangler dev` is supported by any Linux distributions providing `glibc 2.31` or higher (e.g. Ubuntu 20.04/22.04, Debian 11/12, Fedora 37/38/39), macOS version 11 or higher, and Windows (x86-64 architecture).
:::
- `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.
- `--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.
- `--legacy-assets` <Type text="string" /> <MetaInfo text="optional deprecated, use `--assets`" />
- Folder of static assets to be served.
- `--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.
- `--node-compat` <Type text="boolean" /> <MetaInfo text="optional" />
- Enable Node.js compatibility.
- `--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=*+*+*+*+*`.
- `--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/local-development/) 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.
- `--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.
- `--legacy-assets` <Type text="string" /> <MetaInfo text="optional deprecated, use `--assets`" />
- Folder of static assets to be served.
- `--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.
- `--node-compat` <Type text="boolean" /> <MetaInfo text="optional" />
- Enable node.js compatibility.
- `--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 or bindings 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`.
- `--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.
<Render file="wrangler-commands/global-flags" product="workers" />
---
## `publish`
Publish your Worker to Cloudflare.
```txt
wrangler publish [OPTIONS]
```
:::note
This command has been deprecated as of v3 in favor of [`wrangler deploy`](#deploy). It will be removed in v4.
:::
---
## `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
```
## `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" />
### `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).
- `--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.
:::
### `publish`
Publish a directory of static assets as a Pages deployment.
```txt
wrangler pages publish [<DIRECTORY>] [OPTIONS]
```
<Render file="wrangler-commands/global-flags" product="workers" />
:::note
This command has been deprecated as of v3 in favor of [`wrangler pages deploy`](#deploy-1). It will be removed in v4.
:::
### `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" />
---
## `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" />
---
## `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 $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`.
<Render file="wrangler-commands/global-flags" product="workers" />
:::note
`wrangler login` uses all the available scopes by default if no flags are provided.
:::
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/).
<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 from bindings and module rules in configuration.
```txt
wrangler types [<PATH>] [OPTIONS]
```
:::note
The `--experimental-include-runtime` flag dynamically generates runtime types according to the `compatibility_date` and `compatibility_flags` defined in your [config file](/workers/wrangler/configuration/).
It is a replacement for the [`@cloudflare/workers-types` package](https://www.npmjs.com/package/@cloudflare/workers-types), so that package, if installed, should be uninstalled to avoid any potential conflict.
After running the command, you must add the path of the generated runtime types file to the [`compilerOptions.types` field](https://www.typescriptlang.org/tsconfig/#types) in your project's [tsconfig.json](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) file.
You may use the shorthand `--x-include-runtime` flag in place of `--experimental-include-runtime` anywhere it is mentioned.
The minimum required Wrangler version to use this command is 3.66.0.
:::
- `PATH` <Type text="string" /> <MetaInfo text="(default: `./worker-configuration.d.ts`)" />
- The path to where **the `Env` 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.
- `--experimental-include-runtime` <Type text="string" /> <MetaInfo text="optional (default: `./.wrangler/types/runtime.d.ts`)" />
- The path to where the **runtime types** file will be written.
- Leave the path blank to use the default option, e.g. `npx wrangler types --x-include-runtime`
- A custom path must be relative to the project root, e.g. `./my-runtime-types.d.ts`
- A custom path must have a `d.ts` extension.
- `--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. `myEnv: 'my dev variable' | 'my prod variable'`).
- If `false`, Wrangler generates generic types (e.g. `myEnv: string`). This is useful when variables change frequently, especially when working across multiple environments.
<Render file="wrangler-commands/global-flags" product="workers" />
---
## `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
```
---
# 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, except that the syntax is `JSON` rather than `TOML`. Throughout this page and the rest of Cloudflare's documentation config 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
The configuration for a Worker can become complex when you define different [environments](/workers/wrangler/environments/), and each environment has its own configuration.
There is a default (top-level) environment and 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.
## 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.
## 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`.
- `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`.
- `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).
- `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.
- `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).
- `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.
- `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`.
- `minify` <Type text="boolean" /> <MetaInfo text="optional" />
- Minify the Worker script before uploading.
- `node_compat` <Type text="boolean" /> <MetaInfo text="optional" />
- Deprecated — Instead, [enable the `nodejs_compat` compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag), which enables both built-in Node.js APIs, and adds polyfills as necessary.
Setting `node_compat = true` will add polyfills for Node.js built-in modules and globals to your Worker's code, when bundled with Wrangler.
This is powered by `@esbuild-plugins/node-globals-polyfill` which in itself is powered by [rollup-plugin-node-polyfills](https://github.com/ionic-team/rollup-plugin-node-polyfills/).
- `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.
### Usage model
As of March 1, 2024 the [usage model](/workers/platform/pricing/#workers) configured in your Worker's configuration file will be ignored. The [Standard](/workers/platform/pricing/#example-pricing-standard-usage-model) usage model applies.
Some Workers Enterprise customers maintain the ability to change usage models. Your usage model must be configured through the Cloudflare dashboard by going to **Workers & Pages** > select your Worker > **Settings** > **Usage Model**.
## 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.
- `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/setup/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
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 30,000 milliseconds (30 seconds).
<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/local-development/) 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_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_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>
```toml title="wrangler.toml"
[[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/local-development/) 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/local-development/) 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.
- `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="required" />
- Folder of static assets to be served.
- `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" /> <MetaInfo text="optional, defaults to false" />
- Controls whether static assets are fetched directly, or a Worker script is invoked. Learn more about fetching assets when using [`run_worker_first`](/workers/static-assets/routing/#invoking-worker-script-ahead-of-assets).
- `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/#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 in [assets routing](/workers/static-assets/routing/#not_found_handling).
Example:
<WranglerConfig>
```toml title="wrangler.toml"
assets = { directory = "./public", binding = "ASSETS", html_handling = "force-trailing-slash", not_found_handling = "404-page" }
```
</WranglerConfig>
## Bundling
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
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
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, use the below environmental 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.
:::
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 build`
- `wrangler pages build-env`
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"
}
```
---
# 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
With the release of Wrangler v2, it is no longer necessary to use custom builds to bundle your code via webpack and similar bundlers. Wrangler runs [esbuild](https://esbuild.github.io/) by default as part of the `dev` and `publish` 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>
---
# Deprecations
URL: https://developers.cloudflare.com/workers/wrangler/deprecations/
Review the difference between Wrangler versions, specifically deprecations and breaking changes.
## 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 />
---
# Environments
URL: https://developers.cloudflare.com/workers/wrangler/environments/
import { WranglerConfig } from "~/components";
## Background
Wrangler allows you to deploy the same Worker application with different configuration for each environment. You must configure environments in your Worker application's Wrangler file.
Review the following environments flow:
1. You have created a Worker application named `my-worker`.
2. You create an environment, for example, `dev`, in the Worker's [Wrangler configuration file](/workers/wrangler/configuration/).
3. In the Wrangler configuration file, you configure the `dev` environment by [adding bindings](/workers/runtime-apis/bindings/) and/or [routes](/workers/configuration/routing/routes/).
4. You deploy the Worker using `npx wrangler deploy -e dev`.
5. In the background, Wrangler creates a new Worker named `my-worker-dev`.
6. You can now change your `my-worker` Worker code and configuration, and choose which environment to deploy your changes to.
Environments are used with the `--env` or `-e` flag on `wrangler dev`, `npx wrangler deploy`, and `wrangler secret`.
## Configuration
To create an environment:
1. Open your Worker's Wrangler file.
2. Add `[env.<NAME>]` and change `<NAME>` to the desired name of your environment.
3. Repeat step 2 to create multiple environments.
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`.
Review the layout of an example `[env.dev]` environment that sets up a custom `dev.example.com` route:
<WranglerConfig>
```toml
name = "your-worker"
route = "example.com"
[env.dev]
route = "dev.example.com"
```
</WranglerConfig>
You cannot specify multiple environments with the same name.
Wrangler appends the environment name to the top-level name to deploy a Worker. For example, a Worker project named `my-worker` with an environment `[env.dev]` would deploy a Worker named `my-worker-dev`.
After you have configured your environment, run `npx wrangler deploy` in your Worker project directory for the changes to take effect.
## 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.
[Bindings](/workers/runtime-apis/bindings/) and [environment variables](/workers/configuration/environment-variables/) must be specified per each [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>
You may assign environment-specific [secrets](/workers/configuration/secrets/) by running the command [`wrangler secret put <KEY> -env`](/workers/wrangler/commands/#put).
---
## 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>
In order to use environments with this configuration, you can pass the name of the environment via the `--env` flag.
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.
:::
---
# Install/Update Wrangler
URL: https://developers.cloudflare.com/workers/wrangler/install-and-update/
import { Render } 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. Wrangler requires a Node version of `16.17.0` or later.
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:
<Render file="install_wrangler" />
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:
```sh
npm install wrangler@latest
```
## 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.
---
# 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/setup/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.
* `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
```
## 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`
---
# 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 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**.
---
# 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.
---
# 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.
---
# 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 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**.
---
# 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**.
---
# 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/).
---
# 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 & 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 />
---
# 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
query ZarazEvents(
$zoneTag: string
$limit: uint64!
$start: Date
$end: Date
$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
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
query ZarazTriggers(
$zoneTag: string
$limit: uint64!
$start: Date
$end: Date
$orderBy: [uint64!]
) {
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
query ErroneousResponses(
$zoneTag: string
$limit: uint64!
$start: Date
$end: Date
$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 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. |
---
# 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.
---
# 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.
---
# 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.
---
# 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.
---
# 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 />
---
# 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",
},
],
});
```
---
# 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`.
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/).
---
# 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/).
---
# Variables
URL: https://developers.cloudflare.com/zaraz/variables/
import { DirectoryListing } from "~/components"
<DirectoryListing />
---
# 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**.
---
# 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));
},
};
```
---
# 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](https://developers.cloudflare.com/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's 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.
---
# 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 } 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:
```bash
curl --request PATCH \
"https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{hostname_id}" \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
--header "Content-Type: application/json" \
--data '{
"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" />
---
# 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/
[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/setup/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"`:
```bash
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames" \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
--header "Content-Type: application/json" \
--data '{
"hostname": "{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:
```bash
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames?hostname={hostname}" \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>"
```
5. Then make an API call such as the example below, specifying `"early_hints": "on"`:
```bash
curl --request PATCH \
"https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{id}" \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
--header "Content-Type: application/json" \
--data '{
"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/cloudflare-errors/troubleshooting-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/setup/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/setup/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:
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
```
---
# 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 | |
---
# 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 />
---
# 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](/fundamentals/subscriptions-and-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" />
#### Service continuation
<Render file="get-started-service-continuation" />
---
# Get started
URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/start/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# 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 />
---
# 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.
## 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/
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
#### 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 won't 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](https://developers.cloudflare.com/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.
#### 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](https://developers.cloudflare.com/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: "Hello World Worker",
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: "Hello World Worker",
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: "Hello World Worker",
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: "Hello World Worker",
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
```
---
# 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 });
}
},
};
```
---
# 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.
## 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.
---
# Platform
URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/platform/
import { DirectoryListing } from "~/components"
<DirectoryListing />
---
# 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 (eg.`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" />
---
# Get started
URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/get-started/
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.
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: "Hello World Worker",
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`:
```sh
npm install 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 v2, 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 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: "Hello World Worker",
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).
---
# Bulk import to D1 using REST API
URL: https://developers.cloudflare.com/d1/tutorials/import-to-d1-with-rest-api/
import { Render, Steps } 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.
```sh
npm install @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.
---
# Query D1 using Prisma ORM
URL: https://developers.cloudflare.com/d1/tutorials/d1-and-prisma-orm/
import { WranglerConfig } 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 example shows you how to set up and deploy a Cloudflare Worker that is accessing a D1 database from scratch.
### 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 `yes` to deploying your Worker.
Once you deploy your Worker, you should be able to preview your Worker at `https://prisma-d1-example.USERNAME.workers.dev`, which displays "Hello World" in the browser.
### 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
npm install prisma --save-dev
```
Next, install the Prisma Client package and the driver adapter for D1:
```sh
npm install @prisma/client
npm install @prisma/adapter-d1
```
Finally, bootstrap the files required by Prisma ORM using the following command:
```sh
npx prisma 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:
```diff
generator client {
provider = "prisma-client-js"
+ 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 EEUR
Created your database using D1's new storage backend. The new storage backend is not yet recommended for production workloads, but backs up your data via
point-in-time restore.
[[d1_databases]]
binding = "DB" # i.e. available in your Worker on env.DB
database_name = "prisma-demo-db"
database_id = "__YOUR_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"]
[[d1_databases]]
binding = "DB" # i.e. available in your Worker on env.DB
database_name = "prisma-demo-db"
database_id = "__YOUR_D1_DATABASE_ID__"
```
</WranglerConfig>
`__YOUR_D1_DATABASE_ID__` should be replaced 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`.
However, D1 has a [migration system](/d1/reference/migrations), and the Prisma CLI provides tools that allow you to generate SQL statements for schema changes. In the following steps, you will use D1's migration system and the Prisma CLI to create and run a migration against 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:
```
migrations/
└── 0001_create_user_table.sql
```
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:
```diff
model User {
id Int @id @default(autoincrement())
email String @unique
name String?
}
```
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:
```sql
-- CreateTable
CREATE TABLE "User" (
"id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
"email" TEXT NOT NULL,
"name" TEXT
);
-- CreateIndex
CREATE UNIQUE INDEX "User_email_key" ON "User"("email");
```
`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 local and remote development. You will test the Worker locally and 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
```
### 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:
```ts
import { PrismaClient } from "@prisma/client";
import { PrismaD1 } from "@prisma/adapter-d1";
export interface Env {
DB: D1Database;
}
export default {
async fetch(request, env, ctx): Promise<Response> {
const adapter = new PrismaD1(env.DB);
const prisma = new PrismaClient({ adapter });
const users = await prisma.user.findMany();
const result = JSON.stringify(users);
return new Response(result);
},
} satisfies ExportedHandler<Env>;
```
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).
---
# 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.
---
# Building the App Frontend and UI
URL: https://developers.cloudflare.com/durable-objects/get-started/video-series/app-frontend/
import { Details, DirectoryListing, Stream } from "~/components";
<Stream
id="efc08fd03da0dfebd2e4402af519acb5"
title="Building the App Frontend and UI"
thumbnail="2.5s"
/>
Now, we're moving to the frontend. In this video, we'll set up the frontend starter code (the starter code is located in the Veet GitHub repository), connect to Durable Objects using a call room ID, and display a local video preview.
Useful links:
- [GitHub code](https://github.com/megaconfidence/veet)
<Details header="Video series" >
<DirectoryListing folder="durable-objects/get-started/video-series" />
</Details>
---
# Deploy your Video Call app
URL: https://developers.cloudflare.com/durable-objects/get-started/video-series/deploy-app/
import { Details, DirectoryListing, Stream } from "~/components";
<Stream
id="aaa652e0e05bc09ac35451d9cbd4b341"
title="Deploy your Video Call app"
thumbnail="2.5s"
/>
We're almost done with the project, and in this video, we'll add the finishing touches. Learn how to handle call disconnections, wire up essential media controls like muting/unmuting and video toggling, and integrate a TURN server to ensure reliable connections even behind firewalls. By the end of this video, your app will be fully functional and ready for deployment.
Useful links:
- [GitHub code](https://github.com/megaconfidence/veet)
- [TURN service](/calls/turn/)
<Details header="Video series" >
<DirectoryListing folder="durable-objects/get-started/video-series" />
</Details>
---
# What are Durable Objects?
URL: https://developers.cloudflare.com/durable-objects/get-started/video-series/durable-objects/
import { Details, DirectoryListing, Stream } from "~/components";
<Stream
id="fe3a2f97642951e692e86b3af36a4251"
title="What are Durable Objects?"
thumbnail="2.5s"
/>
In this video, we will show how Durable Objects work and start building a video call app together.
Useful links:
- [Sign up](https://dash.cloudflare.com/sign-up) for a Cloudflare account
<Details header="Video series" >
<DirectoryListing folder="durable-objects/get-started/video-series" />
</Details>
---
# Introduction
URL: https://developers.cloudflare.com/durable-objects/get-started/video-series/intro/
import { Details, DirectoryListing, Stream } from "~/components";
<Stream
id="558cdd841276a1aba1426af6293d6d15"
title="Introduction to Durable Objects"
thumbnail="2.5s"
/>
In this episode, we will present an overview of the final project, discuss its underlying architecture, and access resources to set up the project locally.
Useful links:
- [GitHub code](https://github.com/megaconfidence/veet)
<Details header="Video series" >
<DirectoryListing folder="durable-objects/get-started/video-series" />
</Details>
---
# Video series
URL: https://developers.cloudflare.com/durable-objects/get-started/video-series/
import { DirectoryListing, Stream } from "~/components";
Building stateful apps on a serverless architecture has been difficult until Cloudflare's Durable Objects - a powerful API that enables you to easily build stateful serverless apps on Workers. In this series of videos, we will show how Durable Objects work and start building a video call app together.
To get started, [create an account](https://dash.cloudflare.com/sign-up) on Cloudflare today for free.
<DirectoryListing folder="durable-objects/get-started/video-series" />
---
# Make and Answer WebRTC calls
URL: https://developers.cloudflare.com/durable-objects/get-started/video-series/make-answer-webrtc-calls/
import { Details, DirectoryListing, Stream } from "~/components";
<Stream
id="3b3a88940d3b1c635dbb6df0516218ab"
title="Make and Answer WebRTC calls"
thumbnail="2.5s"
/>
In this video, we'll build on the frontend we set up earlier by adding functionality for making and answering WebRTC video calls. You'll learn how to create peer-to-peer connections, handle ICE candidates, and seamlessly send and receive video streams between users.
Useful links:
- [GitHub code](https://github.com/megaconfidence/veet)
<Details header="Video series" >
<DirectoryListing folder="durable-objects/get-started/video-series" />
</Details>
---
# Real-time messaging with WebSockets
URL: https://developers.cloudflare.com/durable-objects/get-started/video-series/real-time-messaging/
import { Details, DirectoryListing, Stream } from "~/components";
<Stream
id="a02e5f9e58999d96c3ec9dbb0efb9707"
title="Real-time messaging with WebSockets"
thumbnail="2.5s"
/>
Now, we'll take it a step further by enabling our server to receive and broadcast messages. In this video, you'll learn how to route and broadcast incoming messages from WebSocket connections and implement error handling such as closed WebSocket connections. By the end, you will have completed the backend for our video call app.
Useful links:
- [GitHub code](https://github.com/megaconfidence/veet)
<Details header="Video series" >
<DirectoryListing folder="durable-objects/get-started/video-series" />
</Details>
---
# Create a Serverless Websocket 'Backend'
URL: https://developers.cloudflare.com/durable-objects/get-started/video-series/serverless-websocket/
import { Details, DirectoryListing, Stream } from "~/components";
<Stream
id="86c64a50e0ea53dadd1ea1194bdeda92"
title="Create a Serverless Websocket 'Backend'"
thumbnail="2.5s"
/>
In this video, we'll create a WebSocket backend using serverless technology, making the process simpler than ever before. You'll learn how to create your first Durable Object, set up a WebSocket server to coordinate connections, and keep track of connected clients.
Useful links:
- [CLI command](/pages/get-started/c3/) for creating new Workers and Pages projects
- [Hopscotch.io](https://hoppscotch.io/) for local WebSocket testing
- [GitHub code](https://github.com/megaconfidence/veet)
<Details header="Video series" >
<DirectoryListing folder="durable-objects/get-started/video-series" />
</Details>
---
# 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: "Hello World Worker Using 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 like 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).
---
# 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: "Hello World Worker",
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:
```sh
npm install 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.
---
# 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 images
URL: https://developers.cloudflare.com/images/manage-images/serve-images/
import { DirectoryListing } from "~/components"
<DirectoryListing />
---
# 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.
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.
---
# 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/).
### 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.
Check runs will appear like the following in your repository.
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.
#### 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.
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.
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.
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.
---
# 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="0b28fdd5938c4929bd7fdedcd167044d" title="Deploy NextJS to your Workers Application" thumbnail="2.5s" />
<DirectoryListing />
---
# 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
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, select _Next.js (Static HTML Export)_ as your **Framework preset**. Your selection will provide the following information.
<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/).
---
# 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" />
---
# 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;
};
```
---
# 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];
```
---
# 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/
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
```sh
npm install @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-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/
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
```sh
npm install @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.
### 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/
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
```sh
npm install @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/
The hCaptcha Pages Plugin validates hCaptcha tokens.
## Installation
```sh
npm install @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/
The Honeycomb Pages Plugin automatically sends traces to Honeycomb for analysis and observability.
## Installation
```sh
npm install @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.
### 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 } 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/
:::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
```sh
npm install @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).
---
# Static Forms
URL: https://developers.cloudflare.com/pages/functions/plugins/static-forms/
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
```sh
npm install @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.
---
# Stytch
URL: https://developers.cloudflare.com/pages/functions/plugins/stytch/
The Stytch Pages Plugin is a middleware which validates all requests and their `session_token`.
## Installation
```sh
npm install @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`.
---
# Turnstile
URL: https://developers.cloudflare.com/pages/functions/plugins/turnstile/
[Turnstile](/turnstile/) is Cloudflare's smart CAPTCHA alternative.
The Turnstile Pages Plugin validates Cloudflare Turnstile tokens.
## Installation
```sh
npm install @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/
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:
```sh
npm install @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.
---
# 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.
Inside of your site dashboard, select **Site Settings**, and then **Build & Deploy**.
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/`.
## 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/
In this tutorial, you will learn how to deploy your Vercel application to Cloudflare Pages.
:::note
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.
:::
## 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. 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.
Inside of your site dashboard, select **Settings**, then **General**.
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`.
## Creating 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.
## Adding a custom domain
To use a custom domain for your Pages project, [add a custom domain](/pages/configuration/custom-domains/) that is the same custom domain as your currently deployed Vercel application. When Pages finishes the initial deploy of your site, you will need to delete the Vercel application to start sending requests to Cloudflare Pages.
:::note
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/).
:::
## Cleaning up your old application and assigning the domain
In your DNS settings for your domain, make sure that you have updated the CNAME record for your domain from Vercel to Cloudflare Pages. With your DNS record updated, requests will go to your Pages application.
By completing this guide, you have successfully migrated your Vercel project to Cloudflare Pages.
---
# 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.
---
# Add a React form with Formspree
URL: https://developers.cloudflare.com/pages/tutorials/add-a-react-form-with-formspree/
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:
```sh
npm install --save @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**.
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.
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:
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**.
You will then be presented with instructions on how to integrate your new form.
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 an API for your front end using Pages Functions
URL: https://developers.cloudflare.com/pages/tutorials/build-an-api-with-pages-functions/
import { Stream } 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 start
```
### 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.
With `npm`:
```sh
npm install react-router-dom@6
```
With `yarn`:
```sh
yarn add react-router-dom@6
```
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)
---
# 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 } 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:
```sh title="Installing the Sanity client and creating a new project"
npm install -g @sanity/cli && sanity 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 title="Starting the Sanity studio"
cd my-sanity-project
sanity 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.
### 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.
```sh title="Deploying the studio"
sanity 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.
## 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:
```sh title="Creating a new Nuxt.js project"
npx create-nuxt-app 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 title="Starting a Nuxt.js development server"
cd blog
yarn dev
```
### Integrating Sanity.io
After your Nuxt.js application is set up, add Sanity's `@sanity/nuxt` plugin to your Nuxt project:
```sh title="Adding @nuxt/sanity"
yarn add @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:
```sh title="Add sanity-blocks-vue-component package"
yarn add 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:
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.
---
# Create a HTML form
URL: https://developers.cloudflare.com/pages/tutorials/forms/
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.
---
<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:
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
```
## 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:
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:
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
npm run deploy
```
Once deployed, media assets are fetched and served from the R2 bucket.
## **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/).
---
# 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: "Hello World Worker",
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.
```sh
npx wrangler kv namespace create crawler_links
npx wrangler 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):
```sh
npm install @cloudflare/puppeteer --save-dev
npm install 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.
```sh
npx wrangler 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:
```sh
npx wrangler 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/setup/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/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/Headers/If-Match), [`If-None-Match`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match), [`If-Modified-Since`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Modified-Since), and [`If-Unmodified-Since`](https://developer.mozilla.org/en-US/docs/Web/HTTP/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 />
---
# Authentication
URL: https://developers.cloudflare.com/r2/api/s3/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 **Account details**, select **Manage R2 API tokens**.
3. Select [**Create API token**](https://dash.cloudflare.com/?to=/:account/r2/api-tokens).
4. Select the **R2 Token** text to edit your API token name.
5. Under **Permissions**, choose a permission types for your token. Refer to [Permissions](#permissions) for information about each option.
6. (Optional) If you select the **Object Read and Write** or **Object Read** permissions, you can scope your token to a set of buckets.
7. Select **Create 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/setup/find-account-and-zone-ids/).
Buckets created with jurisdictions must be accessed via jurisdiction-specific `endpoint`s:
* 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, and edit bucket configurations in addition to list, write, and read object access. |
| Admin Read only | Allows the ability to list buckets and view bucket configuration in addition to list and read object access. |
| 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. |
## 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/setup/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/setup/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. There are four relevant permission groups for R2.
<table>
<tbody>
<th colspan="5" rowspan="1">
Permission group
</th>
<th colspan="5" rowspan="1">
Resource
</th>
<th colspan="5" rowspan="1">
Permission
</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">
Admin Read & Write
</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">
Admin Read only
</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">
Object Read & Write
</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">
Object Read only
</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.
:::
---
# Presigned URLs
URL: https://developers.cloudflare.com/r2/api/s3/presigned-urls/
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/s3/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.
## 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)
## 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.
:::
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.
If the Worker 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.
```ts
import { AwsClient } from "aws4fetch";
const r2 = 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 });
}
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 r2.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;
```
Notice the total absence of any configuration or token secrets present in the Worker code. Instead, in your [Wrangler configuration file](/workers/wrangler/configuration/), you would create a [binding](/r2/api/workers/workers-api-usage/#3-bind-your-bucket-to-a-worker) to whatever bucket represents the bucket you will upload to. Additionally, authorization is handled in-line with the upload which can reduce latency.
In some cases, Workers lets 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 pre-signed URLs, you would need to sign specific headers and require the sender to send them. You can modify the previous Worker to sign additional headers:
```ts
const signed = await r2.sign(
new Request(url, {
method: "PUT",
}),
{
aws: { signQuery: true },
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. If the caller uses a different header, the presigned URL signature would not match, and they would receive a `403/SignatureDoesNotMatch`.
In a Worker, you would change your upload to:
```ts
const existingObject = await env.DROP_BOX_BUCKET.put(
url.toString().substring(1),
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 });
}
```
Cloudflare Workers currently have some limitations that you may need to consider:
* You cannot upload more than 100 MiB (200 MiB for Business customers) to a Worker.
* 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 depends on R2's extension for conditional uploads. Amazon's S3 service does not offer such functionality at this time.
## 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/)
---
# 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: "Hello World Worker",
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",
},
});
}
},
};
```
:::caution[Prevent potential errors when accessing request.body]
The body of a [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) can only be accessed once. If you previously used `request.formData()` in the same request, you may encounter a TypeError when attempting to access `request.body`.<br/><br/>
To avoid errors, create a clone of the Request object with `request.clone()` for each subsequent attempt to access a Request's body.
Keep in mind that Workers have a [memory limit of 128MB per Worker](https://developers.cloudflare.com/workers/platform/limits#worker-limits) and loading particularly large files into a Worker's memory multiple times may reach this limit. To ensure memory usage does not reach this limit, consider using [Streams](https://developers.cloudflare.com/workers/runtime-apis/streams/).
:::
## 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/)
---
# 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.
---
# 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: "Hello World Worker",
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:
```sh title="Install Resend"
npm install 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/)
---
# 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
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-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[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` 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
};
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-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 => [
#=> …,
#=> …,
#=> …,
#=> ]
#=> }
```
---
# 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
```
---
# 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);
```
---
# S3 SDKs
URL: https://developers.cloudflare.com/r2/examples/aws/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# 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` |
| 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's 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 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:
* Change **Output Mode** to "Advanced"
*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's 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
---
# 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.
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/)
---
# 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.
---
# API Reference
URL: https://developers.cloudflare.com/workers-ai/function-calling/embedded/api-reference/
Learn more about the API reference for [embedded function calling](/workers-ai/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
\}
---
# Get Started
URL: https://developers.cloudflare.com/workers-ai/function-calling/embedded/get-started/
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.
```sh
npm install @cloudflare/ai-utils --save
```
## 3. Add Workers AI Embedded function calling
Update the `index.ts` file in your application directory with the following code:
```ts title="Embedded function calling example"
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>;
```
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/function-calling/embedded/api-reference/).
---
# Embedded
URL: https://developers.cloudflare.com/workers-ai/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/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/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/tutorials/image-generation-playground" />
</Details>
---
# Build an AI Image Generator Playground (Part 1)
URL: https://developers.cloudflare.com/workers-ai/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/tutorials/image-generation-playground" />
</Details>
---
# Store and Catalog AI Generated Images with R2 (Part 3)
URL: https://developers.cloudflare.com/workers-ai/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/tutorials/image-generation-playground" />
</Details>
---
# How to Build an Image Generator using Workers AI
URL: https://developers.cloudflare.com/workers-ai/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/tutorials/image-generation-playground" />
</Details>
---
# 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/setup/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/setup/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/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 }}
```
---
# 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/setup/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/setup/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).
---
# 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.
---
# Advanced setups
URL: https://developers.cloudflare.com/workers/ci-cd/builds/advanced-setups/
## Monorepos
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
├── shared/
│ └── utils/
└── 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 deploy command to include the flag `--env: <environment name>` in the build configurations.
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.toml`. 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` respectively.
---
# 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/frameworks/) 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.
:::
### Runtime
| Tool | Default version | Environment variable | File |
| ----------- | --------------- | -------------------- | ---------------------------- |
| **Go** | 1.23.0 | `GO_VERSION` | |
| **Node.js** | 22.9.0 | `NODE_VERSION` | .nvmrc, .node-version |
| **Python** | 3.12.5 | `PYTHON_VERSION` | .python-version, runtime.txt |
| **Ruby** | 3.3.5 | `RUBY_VERSION` | .ruby-version |
### Tools and langauges
| Tool | Default version | Environment variable |
| ----------- | ---------------- | -------------------- |
| **Bun** | 1.1.33 | `BUN_VERSION` |
| **Hugo** | extended_0.134.3 | `HUGO_VERSION` |
| **npm** | 10.8.3 | |
| **yarn** | 4.5.0 | `YARN_VERSION` |
| **pnpm** | 9.10.0 | `PNPM_VERSION` |
| **pip** | 24.2 | |
| **gem** | 3.5.19 | |
| **poetry** | 1.8.3 | |
| **pipx** | 1.7.1 | |
| **bundler** | 2.4.10 | |
## 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`. |
| **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 versions upload` | Upload a [version](/workers/configuration/versions-and-deployments/) of your Worker without deploying it as the Active Deployment. |
| `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). |
### 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/frameworks/) 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/frameworks/framework-guides" />
---
# Builds
URL: https://developers.cloudflare.com/workers/ci-cd/builds/
Workers Builds allows you to connect an _existing Worker_ to its GitHub or GitLab repository, enabling automated builds and deployments for your project on push.
Support for creating a _new Worker_ from importing a Git repository is coming soon.
## Get started
If you have an existing Worker and have pushed the project to a Git repository, you can now connect the repository to your Worker, enabling automatic builds and deployments.
To set up builds for your Worker:
1. Select your Worker in the [Workers & Pages Dashboard](https://dash.cloudflare.com) and navigate to **Settings > Build**.
2. Select the Git provider you would like to connect to or select **Connect** and follow the prompts to install the Cloudflare [Git integration](/workers/ci-cd/builds/git-integration/) on your Git account.
3. Configure your [build settings](/workers/ci-cd/builds/configuration/) by selecting your desired Git repository, branch, and configure commands for your build.
4. Push a commit to your Git repository to trigger a build and deploy for 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 disable automatic builds and deployments from your Git repository, go to **Settings** > **Builds** and select **Disconnect** under **Git Repositories**. 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/
## Limits
While in open beta, the following limits are applicable for Workers Builds. Please note, these are subject to change while in beta.
| Metric | Description | Limit |
| --------------------- | ---------------------------------------------------------------------- | --------- |
| **Build Minutes** | The amount of minutes that it takes to build a project. | Unlimited |
| **Concurrent Builds** | Number of builds that run in parallel across an account. | 1 |
| **Build Timeout** | The amount of minutes that a build can be run before it is terminated. | 20 mins |
| **CPU** | Number of CPU cores available to your build | 2 CPUs |
| **Memory** | Amount of memory available to the build. | 8GB |
| **Disk space** | Disk space available to your build | 8GB |
## Future pricing
During the beta, Workers Builds will be free to try with the limits stated above.
In the future, once Workers Builds becomes generally available, you can expect the following updates to the limits and pricing structure.
| Metric | Workers Free | Paid |
| ------------------------- | ------------- | ---------------------------------- |
| **Build Minutes / Month** | 3,000 minutes | 6,000 minutes (then +$0.005 / min) |
| **Concurrent Builds** | 1 | 6 |
---
# 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`.
:::
### 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).
---
# 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).
---
# 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.
---
# 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 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-wranglertoml--wranglerjson-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.
## 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
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 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>
:::note
The `zone_id` and `zone_name` options are interchangeable. However, if using Cloudflare for SaaS with a `*/*` pattern, use the `zone_name` option to avoid errors. Currently, [publishing `*/*` routes with a `zone_id` option fails with an `Invalid URL` error](https://github.com/cloudflare/workers-sdk/issues/2953).
:::
## 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">
```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.
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 modification](/rules/transform/request-header-modification/) rule:
<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-5) 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
Due to [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 Durable Object Worker, 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.
### 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, your Durable Object Worker will define both your Durable Object class and the 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.
:::
## 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).
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-4) and [`deployments`](/workers/wrangler/commands/#list-5) 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.
---
# Fauna
URL: https://developers.cloudflare.com/workers/databases/native-integrations/fauna/
import { Render } from "~/components";
[Fauna](https://fauna.com/) is a true serverless database that combines document flexibility with native relational capabilities, offering auto-scaling, multi-active replication, and HTTPS connectivity.
<Render file="database_integrations_definition" />
## Set up an integration with Fauna
To set up an integration with Fauna:
1. You need to have an existing Fauna database to connect to. [Create a Fauna database with demo data](https://docs.fauna.com/fauna/current/get-started/quick-start/?lang=javascript#create-a-database).
2. Once your database is created with demo data, you can query it directly using the Shell tab in the Fauna dashboard:
```sh
Customer.all()
```
3. Add the Fauna 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** > **Fauna**.
5. Follow the setup flow, selecting the database created in step 1.
4. In your Worker, install the `fauna` driver to connect to your database and start manipulating data:
```sh
npm install fauna
```
5. The following example shows how to make a query to your Fauna database in a Worker. The credentials needed to connect to Fauna have been automatically added as secrets to your Worker through the integration.
```javascript
import { Client, fql } from "fauna";
export default {
async fetch(request, env) {
const fauna = new Client({
secret: env.FAUNA_SECRET,
});
const query = fql`Customer.all()`;
const result = await fauna.query(query);
return Response.json(result.data);
},
};
```
6. You can manage the Cloudflare Fauna integration from the [Fauna Dashboard](https://dashboard.fauna.com/):
- To view Fauna keys for an integrated Cloudflare Worker, select your database and click the **Keys** tab.
Keys for a Cloudflare Worker integration are prepended with `_cloudflare_key_`.
You can delete the key to disable the integration.
- When you connect a Cloudflare Worker to your database, Fauna creates an OAuth client app in your Fauna account.
To view your account's OAuth apps, go to **Account Settings > OAuth Apps** in the Fauna Dashboard.
You can delete the app to disable the integration.
To learn more about Fauna, refer to [Fauna's official documentation](https://docs.fauna.com/).
---
# 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.
---
# Neon
URL: https://developers.cloudflare.com/workers/databases/native-integrations/neon/
import { Render } 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.
<Render file="database_integrations_definition" />
## Set up an integration with Neon
To set up an integration with Neon:
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. Add the Neon 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** > **Neon**.
5. Follow the setup flow, selecting the database created in step 1.
5. In your Worker, install the `@neondatabase/serverless` driver to connect to your database and start manipulating data:
```sh
npm install @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 automatically added as secrets to your Worker through the integration.
```sql
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).
---
# Database Integrations
URL: https://developers.cloudflare.com/workers/databases/native-integrations/
import { DirectoryListing } from "~/components"
## Background
Connect to databases using the new Database Integrations (beta) experience. Enable Database Integrations in the [Cloudflare dashboard](https://dash.cloudflare.com). With Database Integrations, Cloudflare automatically handles the process of creating a connection string and adding it as secrets to your Worker.
:::note[Making multiple round trip calls to a centralized database from a Worker?]
If your Worker is making multiple round trip calls to a centralized database, your Worker may be a good fit for Smart Placement. Smart Placement speeds up applications by automatically running your Worker closer to your back-end infrastructure rather than the end user. Learn more about [how Smart Placement works](/workers/configuration/smart-placement/).
:::
## Database credentials
If you rotate or delete database credentials, you must delete the integration and go through the setup flow again.
## Database limits
At this time, Database Integrations only support access to one database per provider. To add multiple, you must manually configure [secrets](/workers/configuration/environment-variables/).
## Supported platforms
<DirectoryListing />
---
# Supabase
URL: https://developers.cloudflare.com/workers/databases/native-integrations/supabase/
import { Render } 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.
<Render file="database_integrations_definition" />
## Set up an integration with Supabase
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. Add the Supabase 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** > **Supabase**.
5. Follow the setup flow, selecting the database created in step 1.
5. In your Worker, install the `@supabase/supabase-js` driver to connect to your database and start manipulating data:
```sh
npm install @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 automatically added as secrets to your Worker through the integration.
```sql
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).
---
# PlanetScale
URL: https://developers.cloudflare.com/workers/databases/native-integrations/planetscale/
import { Render } from "~/components";
[PlanetScale](https://planetscale.com/) is a MySQL-compatible platform that makes databases infinitely scalable, easier and safer to manage.
<Render file="database_integrations_definition" />
## 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. Add the PlanetScale 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** > **PlanetScale**.
5. Follow the setup flow, selecting the database created in step 1.
5. In your Worker, install the `@planetscale/database` driver to connect to your PlanetScale database and start manipulating data:
```sh
npm install @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 automatically added as secrets to your Worker through the integration.
```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/).
---
# Turso
URL: https://developers.cloudflare.com/workers/databases/native-integrations/turso/
import { Render } 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.
<Render file="database_integrations_definition" />
## 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. Add the Turso 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** > **Turso**.
5. Follow the setup flow, selecting the database created in step 1.
5. In your Worker, install the Turso client library:
```sh
npm install @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 automatically added as [secrets](/workers/configuration/secrets/) to your Worker through the integration.
```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).
---
# Upstash
URL: https://developers.cloudflare.com/workers/databases/native-integrations/upstash/
import { Render } 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.
<Render file="database_integrations_definition" />
## 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. Add the Upstash Redis 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 **Settings** > **Integrations** > **Upstash Redis**.
5. Follow the setup flow, selecting the database created in step 1.
4. In your Worker, install the `@upstash/redis`, a HTTP client to connect to your database and start manipulating data:
```sh
npm install @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 automatically added as secrets to your Worker through the integration.
```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. Add the Upstash Kafka 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 **Settings** > **Integrations** > **Upstash Kafka**.
5. Follow the setup flow, selecting the cluster and topic.
3. In your Worker, install `@upstash/kafka`, a HTTP/REST based Kafka client:
```sh
npm install @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. Add the Upstash QStash 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** > **Upstash QStash**.
5. Follow the setup flow.
3. In your Worker, install the `@upstash/qstash`, a HTTP client to connect to your database QStash endpoint:
```sh
npm install @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/native-integrations/xata/
import { Render } 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.
<Render file="database_integrations_definition" />
## 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. Add the Xata 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** > **Xata**.
5. Follow the setup flow, selecting the database created in step 1.
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 automatically added as secrets to your Worker through the integration.
```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).
---
# Angular
URL: https://developers.cloudflare.com/workers/frameworks/framework-guides/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 [<InlineBadge preset="beta" /> 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 <InlineBadge preset="beta" /> Workers Assets, run the following command:
<PackageManagers
type="create"
pkg="cloudflare@latest my-angular-app"
args={"--framework=angular --experimental"}
/>
<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
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
You can serve static assets your Angular application by placing them in [the `./public/` directory](https://angular.dev/reference/configs/file-structure#workspace-configuration-files). This can be useful for resource files such as images, stylesheets, fonts, and manifests.
<Render file="workers-assets-routing-summary" />
---
# Astro
URL: https://developers.cloudflare.com/workers/frameworks/framework-guides/astro/
import {
Badge,
Description,
InlineBadge,
Render,
PackageManagers,
} from "~/components";
In this guide, you will create a new [Astro](https://astro.build/) application and deploy to Cloudflare Workers (with the new [<InlineBadge preset="beta" /> 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 Astro's official setup tool, and provide the option to deploy instantly.
To use `create-cloudflare` to create a new Astro project with <InlineBadge preset="beta" /> Workers Assets, run the following command:
<PackageManagers
type="create"
pkg="cloudflare@latest my-astro-app"
args={"--framework=astro --experimental"}
/>
<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
framework: "Astro",
}}
/>
After setting up your project, change your directory by running the following command:
```sh
cd my-astro-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 Astro application can be fully integrated with the Cloudflare Developer Platform, in both local development and in production, by using product bindings. The [Astro documentation](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#cloudflare-runtime) provides information about configuring bindings and how you can access them in your `locals`.
## Static assets
You can serve static assets your Astro application by placing them in [the `./public/` directory](https://docs.astro.build/en/basics/project-structure/#public). This can be useful for resource files such as images, stylesheets, fonts, and manifests.
<Render file="workers-assets-routing-summary" />
---
# Docusaurus
URL: https://developers.cloudflare.com/workers/frameworks/framework-guides/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 [<InlineBadge preset="beta" /> 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 <InlineBadge preset="beta" /> Workers Assets, run the following command:
<PackageManagers
type="create"
pkg="cloudflare@latest my-docusaurus-app"
args={"--framework=docusaurus --platform=workers"}
/>
<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
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"} />
---
## Static assets
You can serve static assets your Docusaurus application by placing them in [the `./static/` directory](https://docusaurus.io/docs/static-assets). This can be useful for resource files such as images, stylesheets, fonts, and manifests.
---
# Gatsby
URL: https://developers.cloudflare.com/workers/frameworks/framework-guides/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 [<InlineBadge preset="beta" /> 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 <InlineBadge preset="beta" /> Workers Assets, run the following command:
<PackageManagers
type="create"
pkg="cloudflare@latest my-gatsby-app"
args={"--framework=gatsby --experimental"}
/>
<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
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"} />
---
## Static assets
You can serve static assets your Gatsby application by placing them in [the `./static/` directory](https://www.gatsbyjs.com/docs/how-to/images-and-media/static-folder/). This can be useful for resource files such as images, stylesheets, fonts, and manifests.
---
# Next.js
URL: https://developers.cloudflare.com/workers/frameworks/framework-guides/nextjs/
import {
Badge,
Description,
InlineBadge,
Render,
PackageManagers,
Stream,
WranglerConfig
} from "~/components";
## New apps
To create a new Next.js app, pre-configured to run on Cloudflare using [`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare), run:
<PackageManagers
type="create"
pkg="cloudflare@latest my-next-app"
args={"--framework=next --experimental"}
/>
<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
framework: "Next.js",
}}
/>
## Existing Next.js apps
:::note[Minimum required Wrangler version: 3.78.10.]
Check your version by running `wrangler --version`. To update Wrangler, refer to [Install/Update Wrangler](/workers/wrangler/install-and-update/).
:::
### 1. Install @opennextjs/cloudflare
First, install [@opennextjs/cloudflare](https://www.npmjs.com/package/@opennextjs/cloudflare):
```sh
npm install --save-dev @opennextjs/cloudflare
```
### 2. Add a Wrangler configuration file
Then, add a [Wrangler configuration file](/workers/wrangler/configuration/) to the root directory of your Next.js app:
<WranglerConfig>
```toml
main = ".open-next/worker.js"
name = "my-app"
compatibility_date = "2024-09-23"
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.
:::
You configure your Worker and define what resources it can access via [bindings](/workers/runtime-apis/bindings/) in the [Wrangler configuration file](/workers/wrangler/configuration/).
### 3. Update `package.json`
Add the following to the scripts field of your `package.json` file:
```json
"build:worker": "opennextjs-cloudflare",
"dev:worker": "wrangler dev --port 8771",
"preview:worker": "npm run build:worker && npm run dev:worker",
"deploy:worker": "npm run build:worker && wrangler deploy"
```
- `npm run build:worker`: Runs the [@opennextjs/cloudflare](https://www.npmjs.com/package/@opennextjs/cloudflare) adapter. This first builds your app by running `next build` behind the scenes, and then transforms the build output to a format that you can run locally using [Wrangler](/workers/wrangler/) and deploy to Cloudflare.
- `npm run dev:worker`: Takes the output generated by `build:worker` and runs it locally in [workerd](https://github.com/cloudflare/workerd), the open-source Workers Runtime, allowing you to run the app locally in the same environment that it will run in production. If you instead run `next dev`, your app will run in Node.js, which is a different JavaScript runtime from the Workers runtime, with differences in behavior and APIs.
- `npm run preview:worker`: Runs `build:worker` and then `dev:worker`, allowing you to quickly preview your app running locally in the Workers runtime, via a single command.
- `npm run deploy:worker`: Builds your app, and then deploys it to Cloudflare
### 4. Add caching with Workers KV
`opennextjs/cloudflare` uses [Workers KV](/kv/) as the cache for your Next.js app. Workers KV is [fast](https://blog.cloudflare.com/faster-workers-kv) and uses Cloudflare's [Tiered Cache](/cache/how-to/tiered-cache/) to increase cache hit rates. 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 be read by subsequent requests from this cache anywhere in the world.
To enable caching, you must:
#### Create a KV namespace
```sh
npx wrangler@latest kv namespace create NEXT_CACHE_WORKERS_KV
```
#### Add the KV namespace to your Worker
<WranglerConfig>
```toml
[[kv_namespaces]]
binding = "NEXT_CACHE_WORKERS_KV"
id = "<YOUR_NAMESPACE_ID>"
```
</WranglerConfig>
#### Set the name of the binding to `NEXT_CACHE_WORKERS_KV`
As shown above, the name of the binding that you configure for the KV namespace must be set to `NEXT_CACHE_WORKERS_KV`.
### 5. Develop locally
You can continue to run `next dev` when developing locally.
### 6. Preview locally your application and create an OpenNext config file
In step 3, we also added the `npm run preview:worker`, which allows you to quickly preview your app running locally in the Workers runtime, rather than in Node.js.
This allows you to test changes in the same runtime that your app runs in, when deployed to Cloudflare.
To preview your application in such way run:
```sh
npm run preview:worker
```
This command will build your OpenNext application, also creating, if not already present, an `open-next.configs.ts` file for you.
This is necessary if you want to deploy your application with a GibHub/GitLab integration as presented in the next step.
### 7. Deploy to Cloudflare Workers
Either deploy via the command line:
```sh
npm run deploy:worker
```
Or [connect a GitHub or GitLab repository](/workers/ci-cd/), and Cloudflare will automatically build and deploy each pull request you merge to your production branch.
---
## Static assets
You can serve static assets your Next.js application by placing them in the `./public/` directory. This can be useful for resource files such as images, stylesheets, fonts, and manifests.
<Render file="workers-assets-routing-summary" />
---
# Nuxt
URL: https://developers.cloudflare.com/workers/frameworks/framework-guides/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 [<InlineBadge preset="beta" /> 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 <InlineBadge preset="beta" /> Workers Assets, run the following command:
<PackageManagers
type="create"
pkg="cloudflare@latest my-nuxt-app"
args={"--framework=nuxt --experimental"}
/>
<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
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.
## Static assets
You can serve static assets your Nuxt application by placing them in [the `./public/` directory](https://nuxt.com/docs/guide/directory-structure/public). This can be useful for resource files such as images, stylesheets, fonts, and manifests.
<Render file="workers-assets-routing-summary" />
---
# Qwik
URL: https://developers.cloudflare.com/workers/frameworks/framework-guides/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 [<InlineBadge preset="beta" /> 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 <InlineBadge preset="beta" /> Workers Assets, run the following command:
<PackageManagers
type="create"
pkg="cloudflare@latest my-qwik-app"
args={"--framework=qwik --experimental"}
/>
<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
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.
## Static assets
You can serve static assets your Qwik application by placing them in [the `./public/` directory](https://qwik.dev/docs/advanced/static-assets/). This can be useful for resource files such as images, stylesheets, fonts, and manifests.
<Render file="workers-assets-routing-summary" />
---
# Remix
URL: https://developers.cloudflare.com/workers/frameworks/framework-guides/remix/
import {
Badge,
Description,
InlineBadge,
Render,
PackageManagers,
} from "~/components";
In this guide, you will create a new [Remix](https://remix.run/) application and deploy to Cloudflare Workers (with the new [<InlineBadge preset="beta" /> 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 Remix's official setup tool, and provide the option to deploy instantly.
To use `create-cloudflare` to create a new Remix project with <InlineBadge preset="beta" /> Workers Assets, run the following command:
<PackageManagers
type="create"
pkg="cloudflare@latest my-remix-app"
args={"--framework=remix --experimental"}
/>
<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
framework: "Remix",
}}
/>
After setting up your project, change your directory by running the following command:
```sh
cd my-remix-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 Remix application can be fully integrated with the Cloudflare Developer Platform, in both local development and in production, by using product bindings. The [Remix documentation](https://remix.run/docs/en/main/guides/vite#bindings) provides information about configuring bindings and how you can access them in your Remix page loaders.
## Static assets
You can serve static assets your Remix application by placing them in the `./public/` directory. This can be useful for resource files such as images, stylesheets, fonts, and manifests.
<Render file="workers-assets-routing-summary" />
---
# Solid
URL: https://developers.cloudflare.com/workers/frameworks/framework-guides/solid/
import {
Badge,
Description,
InlineBadge,
Render,
PackageManagers,
} from "~/components";
In this guide, you will create a new [Solid](https://www.solidjs.com/) application and deploy to Cloudflare Workers (with the new [<InlineBadge preset="beta" /> 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 <InlineBadge preset="beta" /> Workers Assets, run the following command:
<PackageManagers
type="create"
pkg="cloudflare@latest my-solid-app"
args={"--framework=solid --experimental"}
/>
<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
framework: "Solid",
}}
/>
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.
## Static assets
You can serve static assets your Solid application by placing them in [the `./public/` directory](https://docs.solidjs.com/solid-start/building-your-application/static-assets). This can be useful for resource files such as images, stylesheets, fonts, and manifests.
<Render file="workers-assets-routing-summary" />
---
# Svelte
URL: https://developers.cloudflare.com/workers/frameworks/framework-guides/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 [<InlineBadge preset="beta" /> 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 <InlineBadge preset="beta" /> Workers Assets, run the following command:
<PackageManagers
type="create"
pkg="cloudflare@latest my-svelte-app"
args={"--framework=svelte --experimental"}
/>
<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
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.
## Static assets
You can serve static assets your Svelte application by placing them in [the `./static/` directory](https://kit.svelte.dev/docs/project-structure#project-files-static). This can be useful for resource files such as images, stylesheets, fonts, and manifests.
<Render file="workers-assets-routing-summary" />
---
# JavaScript
URL: https://developers.cloudflare.com/workers/languages/javascript/
## 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)
---
# 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/cloudflare-errors/troubleshooting-cloudflare-5xx-errors/#error-523-origin-is-unreachable) 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:
<WranglerConfig>
```toml
[profile.release]
lto = true
strip = true
codegen-units = 1
```
</WranglerConfig>
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/)
---
# 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.
---
# 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 js 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.new(greeting)
if url.path == "/favicon.ico":
return Response.new("")
return Response.new("Hello world!")
```
## Parse JSON from the incoming request
```python
from js import Response
async def on_fetch(request):
name = (await request.json()).name
return Response.new("Hello, {name}".format(name=name))
```
## Emit logs from your Python Worker
```python
# To use the JavaScript console APIs
from js import console, 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.new("We're testing logging!")
```
## Publish to a Queue
```python
from js import Response, Object
from pyodide.ffi import to_js as _to_js
# 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(to_js({"write": "success"}))
```
## Query a D1 Database
```python
from js 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 js import Response
async def on_fetch(request, env):
await env.FOO.put("bar", "baz")
bar = await env.FOO.get("bar")
return Response.new(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 js import Response
async def on_fetch(request, env):
return Response.new("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:
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 js import Response
def on_fetch(request):
return Response.new("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 js import Response
def on_fetch(request):
return Response.new(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 js import Response
from hello import hello
async def on_fetch(request):
name = (await request.json()).name
return Response.new(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 js import Response
async def on_fetch(request, env):
return Response.new(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
---
# TypeScript
URL: https://developers.cloudflare.com/workers/languages/typescript/
import { TabItem, Tabs } from "~/components";
## TypeScript
TypeScript is a first-class language on Cloudflare Workers. Cloudflare 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`). 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.
### Generate types that match your Worker's configuration (experimental)
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. For example, the [`urlsearchparams_delete_has_value_arg`](/workers/configuration/compatibility-flags/#urlsearchparams-delete-and-has-value-argument) compatibility flag adds optional arguments to some methods, in order to support new additions to the WHATWG URL standard API.
This means the correct TypeScript 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/).
For example, if you have `compatibility_flags = ["nodejs_als"]` in your [Wrangler configuration file](/workers/wrangler/configuration/), then the runtime will allow you to use the [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) class in your worker code, but you will not see this reflected in the type definitions in `@cloudflare/workers-types`.
In order to solve this issue, and to ensure that your type definitions are always up-to-date with your compatibility settings, you can dynamically generate the runtime types (as of `wrangler 3.66.0`):
```bash
npx wrangler types --experimental-include-runtime
```
This will generate a `d.ts` file and (by default) save it to `.wrangler/types/runtime.d.ts`. You will be prompted in the command's output to add that file to your `tsconfig.json`'s `compilerOptions.types` array.
If you would like to commit the file to git, you can provide a custom path. Here, for instance, the `runtime.d.ts` file will be saved to the root of your project:
```bash
npx wrangler types --experimental-include-runtime="./runtime.d.ts"
```
**Note: To ensure that your types are always up-to-date, make sure to run `wrangler types --experimental-include-runtime` after any changes to your config file.**
See [the full list of available flags](/workers/wrangler/commands/#types) for more details.
#### Migrating from `@cloudflare/workers-types` to `wrangler types --experimental-include-runtime`
The `@cloudflare/workers-types` package provides runtime types for each distinct [compatibility date](https://github.com/cloudflare/workerd/tree/main/npm/workers-types#compatibility-dates), which is specified by the user in their `tsconfig.json`. But this package is superseded by the `wrangler types --experimental-include-runtime` command.
Here are the steps to switch from `@cloudflare/workers-types` to using `wrangler types` with the experimental runtime inclusion:
##### Uninstall `@cloudflare/workers-types`
<Tabs> <TabItem label="npm">
```sh
npm uninstall @cloudflare/workers-types
```
</TabItem> <TabItem label="yarn">
```sh
yarn remove @cloudflare/workers-types
```
</TabItem> <TabItem label="pnpm">
```sh
pnpm uninstall @cloudflare/workers-types
```
</TabItem> </Tabs>
##### Generate runtime types using wrangler
```bash
npx wrangler types --experimental-include-runtime
```
This will generate a `.d.ts` file, saved to `.wrangler/types/runtime.d.ts` by default.
##### Update your `tsconfig.json` to include the generated types
```json
{
"compilerOptions": {
"types": ["./.wrangler/types/runtime"]
}
}
```
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.
##### Update your scripts and CI pipelines
When switching to `wrangler types --experimental-include-runtime`, you'll want to ensure that your development process always uses the most up-to-date types. The main thing to remember here is that - regardless of your specific framework or build tools - you should run the `wrangler types --experimental-include-runtime` command before any development tasks that rely on TypeScript. This ensures your editor and build tools always have access to the latest types.
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 --experimental-include-runtime` before the type-checking script in the project:
```json
{
"scripts": {
"dev": "existing-dev-command",
"build": "-existing-build-command",
"type-check": "wrangler types --experimental-include-runtime && tsc"
}
}
```
In CI, you may have separate build and test commands. It is best practice to run `wrangler types --experimental-include-runtime` before other CI commands. 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>
By integrating the `wrangler types --experimental-include-runtime` command into your workflow this way, you ensure that your development environment, builds, and CI processes always use the most accurate and up-to-date types for your Cloudflare Worker, regardless of your specific framework or tooling choices.
### Known issues
#### Transitive loading of `@types/node` overrides `@cloudflare/workers-types`
Your project's dependencies may load the `@types/node` package on their own. As of `@types/node@20.8.4` that package now overrides `Request`, `Response` and `fetch` types (possibly others) specified by `@cloudflare/workers-types` causing type errors.
The way to get around this issue currently is to pin the version of `@types/node` to `20.8.3` in your `package.json` like this:
```json
{
"overrides": {
"@types/node": "20.8.3"
}
}
```
For more information, refer to [this GitHub issue](https://github.com/cloudflare/workerd/issues/1298).
### 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)
---
# Baselime integration
URL: https://developers.cloudflare.com/workers/observability/integrations/baselime-integration/
import { Render } from "~/components"
[Baselime](https://baselime.io/) is an observability solution built for modern cloud-native environments. It combines logs, metrics, and distributed traces to give you full visibility across your microservices at scale.
This integration allows you to connect to a Baselime environment from your Worker to automatically send errors and logs to Baselime with no code changes needed in the Workers application.
:::note
Baselime integration is available to all Enterprise customers and Free, Pro, and Business customers on the [Workers Paid plan](/workers/platform/pricing/).
:::
## How it works
This integration adds a [Tail Worker](/workers/observability/logs/tail-workers) to your application Worker. The Tail Worker automatically sends errors and uncaught exceptions to the Baselime environment you have configured.
This integration supports the following Baselime features:
* **[Logging](https://baselime.io/docs/analysing-data/overview/)**: Request info, logs, and exceptions are all available to be searched for and analyzed.
* **[Error tracking](https://baselime.io/docs/analysing-data/errors/)**: Actively find and be notified of new errors and track their resolution.
:::note
If there are more configuration options that you would like to see, leave us feedback on the [Cloudflare Developer Discord](https://discord.cloudflare.com) (channel name: integrations).
:::
## Set up an integration with Baselime
To set up an integration with Baselime, you need to have a Baselime environment to connect to. If this is your first time using Baselime, you will be prompted to create an account and an environment during the integration setup.
To add the Baselime integration to your Worker:
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Select **Workers & Pages**.
3. In **Overview**, select your Worker.
4. Select **Integrations** > **Baselime**.
5. Follow the setup flow.
Once installed, the integration will automatically start forwarding events to Baselime. To learn more about Baselime, refer to [Baselime's official documentation](https://baselime.io/docs/).
<Render file="wrangler-tail-warning" />
:::caution
Note that automatic distributed tracing is not yet supported via the Baselime integration. To add tracing, follow the [Baselime documentation](https://baselime.io/docs/sending-data/platforms/cloudflare/traces/).
:::
---
# Integrations
URL: https://developers.cloudflare.com/workers/observability/integrations/
import { DirectoryListing } from "~/components";
Send your telemetry data to third parties.
<DirectoryListing />
---
# Sentry
URL: https://developers.cloudflare.com/workers/observability/integrations/sentry/
import { Render } from "~/components"
[Sentry](https://sentry.io/welcome/) is an error tracking and performance monitoring platform that allows developers to diagnose, fix, and optimize the performance of their code.
This integration allows you to connect to a Sentry project from your Worker to automatically send errors and uncaught exceptions to Sentry with no code changes needed in the Workers application.
:::note
Sentry integration is available to all Enterprise customers and Free, Pro, and Business customers on the [Workers Paid plan](/workers/platform/pricing/).
:::
:::caution
This integration is not supported for Pages projects. Pages does not support [Tail Workers](/workers/observability/logs/tail-workers/), and the Sentry integration relies on adding a Tail Worker to your Worker.
:::
## How it works
This integration adds a [Tail Worker](/workers/observability/logs/tail-workers) to your application Worker. The Tail Worker automatically sends errors and uncaught exceptions to the Sentry project you have configured.
This integration supports the following Sentry features:
* **[Data Handling](https://develop.sentry.dev/sdk/data-handling/)**: As a best practice, do not include PII or other sensitive data in the payload sent to Sentry. HTTP headers (for example, `Authorization` or `Cookie`) can be removed before events are forwarded to Sentry.
* **[Sampling](https://docs.sentry.io/platforms/javascript/configuration/sampling/#configuring-the-transaction-sample-rate)**: Sampling can be configured to manage the number and type of events sent to Sentry. Sampling rates can be configured based on the HTTP status code returned by the Worker and for uncaught exceptions. Setting the sampling rate to 100% sends all events to Sentry or setting it to 30% sends approximately 30% of events to Sentry.
* **[Breadcrumbs](https://docs.sentry.io/product/issues/issue-details/breadcrumbs/)**: Breadcrumbs create a trail of events that happened prior to an issue. Breadcrumbs are automatically forwarded to Sentry in the case of an error or exception. These events consist of the `console.log()` from the Worker before the error or exception occurred.
:::note
If there are more configuration options that you would like to see, leave us feedback on the [Cloudflare Developer Discord](https://discord.cloudflare.com) (channel name: integrations).
:::
## Set up an integration with Sentry
To set up an integration with Sentry, you need to have an existing Sentry project to connect to. [Create a Sentry project](https://docs.sentry.io/product/sentry-basics/integrate-frontend/create-new-project), or use an existing project for this integration. Then add the Sentry integration to your Worker.
To add the Sentry integration to your Worker:
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Select **Workers & Pages**.
3. In **Overview**, select your Worker.
4. Select **Integrations** > **Sentry**.
5. Follow the setup flow.
Once installed, the integration will automatically start forwarding matching events to Sentry. To learn more about Sentry, refer to [Sentry's official documentation](https://docs.sentry.io/).
<Render file="wrangler-tail-warning" />
:::caution
Each Cloudflare account can only be linked to one Sentry organization. Use the [Sentry SDK](https://github.com/getsentry/sentry-javascript) in order to send events to projects in more than one Sentry organization.
:::
---
# 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.
:::
:::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/local-development/) - Develop your Workers and connected resources locally via Wrangler and [`workerd`](https://github.com/cloudflare/workerd), for a fast, accurate feedback loop.
---
# 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/local-development/) - Develop your Workers and connected resources locally via Wrangler and 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/local-development/#develop-using-remote-resources-and-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.
## 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.
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.
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/).
---
# 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/local-development/#develop-using-remote-resources-and-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.
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.
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/).
---
# 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** > **Logs**.
3. Select **Add 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
}
]
}
```
---
# 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) <Badge text="New" variant="tip" size="large" />
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" />
---
# 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 [execution logs](/workers/observability/logs/workers-logs/#execution-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/local-development/) - 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.
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/local-development/) - 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.
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">
```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 | Retention |
| ------------------------------------------------------------------ | ---------- |
| Maximum log retention period | 7 Days |
| Maximum logs per account per day<sup>1</sup> | 5 Billion |
| Maximum log size<sup>2</sup> | 128 KB |
<sup>1</sup> While Workers Logs is in open beta, 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 [128 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 November 1, 2024.
:::
<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 | |
---
# 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. --> */}
---
# Wrangler
URL: https://developers.cloudflare.com/workers/platform/changelog/wrangler/
import { ProductReleaseNotes } from "~/components";
{/* <!-- All changelog entries are pulled directly from https://api.github.com/repos/cloudflare/workers-sdk/releases and manipulated in the src/util/release-notes.ts file (getWranglerChangelog() function). This is unique compared to other changelog entries. --> */}
<ProductReleaseNotes />
---
# 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/
## 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` 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=*+*+*+*+*"
```
:::
---
## Syntax
```js
export default {
async scheduled(event, env, ctx) {
ctx.waitUntil(doSomeTaskOnASchedule());
},
};
```
### Properties
- `event.cron` string
- The value of the [Cron Trigger](/workers/configuration/cron-triggers/) that started the `ScheduledEvent`.
- `event.type` string
- The type of event. This will always return `"scheduled"`.
- `event.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.
---
# 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.
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.
---
# 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>
---
# 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.
A subset of the `node:crypto` module is available in Workers. All APIs in the tables below with a ✅ are supported, and unless otherwise noted, work the same way as the implementations in Node.js.
The [WebCrypto API](/workers/runtime-apis/web-crypto/) is also available within Cloudflare Workers.
## Classes
| API | Supported? | Notes |
| --------------------------------------------------------------------------------- | ---------- | ----- |
| [Certificate](https://nodejs.org/api/crypto.html#class-certificate) | ✅ | |
| [Cipher](https://nodejs.org/api/crypto.html#class-cipher) | | |
| [Decipher](https://nodejs.org/api/crypto.html#class-decipher) | | |
| [DiffieHellman](https://nodejs.org/api/crypto.html#class-diffiehellman) | ✅ | |
| [DiffieHellmanGroup](https://nodejs.org/api/crypto.html#class-diffiehellmangroup) | ✅ | |
| [ECDH](https://nodejs.org/api/crypto.html#class-ecdh) | | |
| [Hash](https://nodejs.org/api/crypto.html#class-hash) | ✅ | |
| [Hmac](https://nodejs.org/api/crypto.html#class-hmac) | ✅ | |
| [KeyObject](https://nodejs.org/api/crypto.html#class-keyobject) | ✅ | |
| [Sign](https://nodejs.org/api/crypto.html#class-sign) | | |
| [Verify](https://nodejs.org/api/crypto.html#class-verify) | | |
| [X509Certificate](https://nodejs.org/api/crypto.html#class-x509certificate) | ✅ | |
| [constants](https://nodejs.org/api/crypto.html#cryptoconstants) | | |
## Primes
| API | Supported? | Notes |
| -------------------------------------------------------------------------------------------- | ---------- | ----- |
| [checkPrime](https://nodejs.org/api/crypto.html#cryptocheckprimecandidate-options-callback) | ✅ | |
| [checkPrimeSync](https://nodejs.org/api/crypto.html#cryptocheckprimesynccandidate-options) | ✅ | |
| [generatePrime](https://nodejs.org/api/crypto.html#cryptogenerateprimesize-options-callback) | ✅ | |
| [generatePrimeSync](https://nodejs.org/api/crypto.html#cryptogenerateprimesyncsize-options) | ✅ | |
## Ciphers
| API | Supported? | Notes |
| ----------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------ |
| [createCipher](https://nodejs.org/api/crypto.html#cryptocreatecipheralgorithm-password-options) | | Deprecated, use `createCipheriv` instead |
| [createCipheriv](https://nodejs.org/api/crypto.html#cryptocreatecipherivalgorithm-key-iv-options) | | |
| [createDecipher](https://nodejs.org/api/crypto.html#cryptocreatedecipheralgorithm-password-options) | | Deprecated, use `createDecipheriv` instead |
| [createDecipheriv](https://nodejs.org/api/crypto.html#cryptocreatedecipherivalgorithm-key-iv-options) | | |
| [privateDecrypt](https://nodejs.org/api/crypto.html#cryptoprivatedecryptprivatekey-buffer) | | |
| [privateEncrypt](https://nodejs.org/api/crypto.html#cryptoprivateencryptprivatekey-buffer) | | |
| [publicDecrypt](https://nodejs.org/api/crypto.html#cryptopublicdecryptkey-buffer) | | |
| [publicEncrypt](https://nodejs.org/api/crypto.html#cryptopublicencryptkey-buffer) | | |
## DiffieHellman
| API | Supported? | Notes |
| ----------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----- |
| [createDiffieHellman(prime)](https://nodejs.org/api/crypto.html#cryptocreatediffiehellmanprime-primeencoding-generator-generatorencoding) | ✅ | |
| [createDiffieHellman(primeLength)](https://nodejs.org/api/crypto.html#cryptocreatediffiehellmanprimelength-generator) | ✅ | |
| [createDiffieHellmanGroup](https://nodejs.org/api/crypto.html#cryptocreatediffiehellmangroupname) | ✅ | |
| [createECDH](https://nodejs.org/api/crypto.html#cryptocreateecdhcurvename) | | |
| [diffieHellman](https://nodejs.org/api/crypto.html#cryptodiffiehellmanoptions) | | |
| [getDiffieHellman](https://nodejs.org/api/crypto.html#cryptogetdiffiehellmangroupname) | ✅ | |
## Hash
| API | Supported? | Notes |
| -------------------------------------------------------------------------------------- | ---------- | ----- |
| [createHash](https://nodejs.org/api/crypto.html#cryptocreatehashalgorithm-options) | ✅ | |
| [createHmac](https://nodejs.org/api/crypto.html#cryptocreatehmacalgorithm-key-options) | ✅ | |
| [getHashes](https://nodejs.org/api/crypto.html#cryptogethashes) | ✅ | |
## Keys
| API | Supported? | Notes |
| ------------------------------------------------------------------------------------------------ | ---------- | ----- |
| [createPrivateKey](https://nodejs.org/api/crypto.html#cryptocreateprivatekeykey) | ✅ | |
| [createPublicKey](https://nodejs.org/api/crypto.html#cryptocreatepublickeykey) | ✅ | |
| [createSecretKey](https://nodejs.org/api/crypto.html#cryptocreatesecretkeykey-encoding) | ✅ | |
| [generateKey](https://nodejs.org/api/crypto.html#cryptogeneratekeytype-options-callback) | ✅ | |
| [generateKeyPair](https://nodejs.org/api/crypto.html#cryptogeneratekeypairtype-options-callback) | ✅ | Does not support DSA or DH key pairs |
| [generateKeyPairSync](https://nodejs.org/api/crypto.html#cryptogeneratekeypairsynctype-options) | ✅ | Does not support DSA or DH key pairs |
| [generateKeySync](https://nodejs.org/api/crypto.html#cryptogeneratekeysynctype-options) | ✅ | |
## Sign/Verify
| API | Supported? | Notes |
| ---------------------------------------------------------------------------------------------- | ---------- | ----- |
| [createSign](https://nodejs.org/api/crypto.html#cryptocreatesignalgorithm-options) | | |
| [createVerify](https://nodejs.org/api/crypto.html#cryptocreateverifyalgorithm-options) | | |
| [sign](https://nodejs.org/api/crypto.html#cryptosignalgorithm-data-key-callback) | | |
| [verify](https://nodejs.org/api/crypto.html#cryptoverifyalgorithm-data-key-signature-callback) | | |
## Misc
| API | Supported? | Notes |
| ---------------------------------------------------------------------------------------- | ---------- | ----- |
| [getCipherInfo](https://nodejs.org/api/crypto.html#cryptogetcipherinfonameornid-options) | | |
| [getCiphers](https://nodejs.org/api/crypto.html#cryptogetciphers) | ✅ | |
| [getCurves](https://nodejs.org/api/crypto.html#cryptogetcurves) | ✅ | |
| [secureHeapUsed](https://nodejs.org/api/crypto.html#cryptosecureheapused) | ✅ | |
| [setEngine](https://nodejs.org/api/crypto.html#cryptosetengineengine-flags) | ✅ | |
| [timingSafeEqual](https://nodejs.org/api/crypto.html#cryptotimingsafeequala-b) | ✅ | |
## Fips
| API | Supported? | Notes |
| --------------------------------------------------------------- | ---------- | ----------------------------------- |
| [getFips](https://nodejs.org/api/crypto.html#cryptogetfips) | ✅ | |
| [fips](https://nodejs.org/api/crypto.html#cryptofips) | ✅ | Deprecated, use `getFips()` instead |
| [setFips](https://nodejs.org/api/crypto.html#cryptosetfipsbool) | ✅ | |
## Random
| API | Supported? | Notes |
| -------------------------------------------------------------------------------------------- | ---------- | ----- |
| [getRandomValues](https://nodejs.org/api/crypto.html#cryptogetrandomvaluestypedarray) | ✅ | |
| [randomBytes](https://nodejs.org/api/crypto.html#cryptorandombytessize-callback) | ✅ | |
| [randomFillSync](https://nodejs.org/api/crypto.html#cryptorandomfillsyncbuffer-offset-size) | ✅ | |
| [randomFill](https://nodejs.org/api/crypto.html#cryptorandomfillbuffer-offset-size-callback) | ✅ | |
| [randomInt](https://nodejs.org/api/crypto.html#cryptorandomintmin-max-callback) | ✅ | |
| [randomUUID](https://nodejs.org/api/crypto.html#cryptorandomuuidoptions) | ✅ | |
## Key Derivation
| API | Supported? | Notes |
| ------------------------------------------------------------------------------------------------------------ | ---------- | ------------------------------ |
| [hkdf](https://nodejs.org/api/crypto.html#cryptohkdfdigest-ikm-salt-info-keylen-callback) | ✅ | Does not yet support KeyObject |
| [hkdfSync](https://nodejs.org/api/crypto.html#cryptohkdfsyncdigest-ikm-salt-info-keylen) | ✅ | Does not yet support KeyObject |
| [pbkdf2](https://nodejs.org/api/crypto.html#cryptopbkdf2password-salt-iterations-keylen-digest-callback) | ✅ | |
| [pbkdf2Sync](https://nodejs.org/api/crypto.html#cryptopbkdf2password-salt-iterations-keylen-digest-callback) | ✅ | |
| [scrypt](https://nodejs.org/api/crypto.html#cryptoscryptpassword-salt-keylen-options-callback) | ✅ | |
| [scryptSync](https://nodejs.org/api/crypto.html#cryptoscryptsyncpassword-salt-keylen-options) | ✅ | |
## WebCrypto
| API | Supported? | Notes |
| --------------------------------------------------------- | ---------- | ----- |
| [subtle](https://nodejs.org/api/crypto.html#cryptosubtle) | ✅ | |
| [webcrypto](https://nodejs.org/api/crypto.html#) | ✅ | |
---
# 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).
---
# 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.
---
# 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 polyfills that [Wrangler](/workers/wrangler/) adds to your Worker's code
You can view which APIs are supported using the [Node.js compatibility matrix](https://workers-nodejs-compat-matrix.pages.dev).
## Get Started
To enable built-in Node.js APIs and add polyfills, you need to add the `nodejs_compat` compatibility flag to your wrangler configuration. This also enables `nodejs_compat_v2` as long as your compatibility date 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>
## Built-in Node.js Runtime APIs
The following APIs from Node.js are provided directly by the Workers Runtime when either `nodejs_compat` or `nodejs_compat_v2` are enabled:
<DirectoryListing />
Unless otherwise specified, 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).
## Node.js API Polyfills
To enable built-in Node.js APIs and add polyfills, you need to add the `nodejs_compat` compatibility flag to your wrangler configuration. This also enables `nodejs_compat_v2` as long as your compatibility date is 2024-09-23 or later. [Learn more about the Node.js compatibility flag and v2](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag).
Adding polyfills maximizes compatibility with existing npm packages, while recognizing that not all APIs from Node.js make sense in the context of serverless functions.
Where it is possible to provide a fully functional polyfill of the relevant Node.js API, unenv will do so.
In cases where this is not possible, such as the [`fs`](https://nodejs.org/api/fs.html), unenv adds a module 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.
For a full list of APIs supported, including information on which are mocked, see the [Node.js compatibility matrix](https://workers-nodejs-compat-matrix.pages.dev).
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.
## Enable only AsyncLocalStorage
To enable only the Node.js `AsyncLocalStorage` API, use 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 `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).
### 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.
---
# 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).
---
# 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).
---
# 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
```
---
# 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).
---
# 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).
---
# 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 } 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>
```js
import { WorkerEntrypoint, RpcTarget } from "cloudflare:workers";
class Counter extends RpcTarget {
#value = 0;
increment(amount) {
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")
}
}
```
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>
```js
export default {
async fetch(request, 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);
}
}
```
:::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:
```js
// Two round trips.
using counter = await env.COUNTER_SERVICE.getCounter();
await counter.increment();
```
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`:
```js
// Only one round trip! Note the missing `await`.
using promiseForCounter = env.COUNTER_SERVICE.getCounter();
await promiseForCounter.increment();
```
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:
```js
import { WorkerEntrypoint } from "cloudflare:workers";
export class MyService extends WorkerEntrypoint {
async foo() {
return {
bar: {
baz: () => "qux"
}
}
}
}
```
```js
export default {
async fetch(request, env) {
using foo = env.MY_SERVICE.foo();
let baz = await foo.bar.baz();
return new Response(baz);
}
}
```
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.
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.
```js
using counter = env.COUNTER_SERVICE.getCounter();
await env.ANOTHER_SERVICE.useCounter(counter);
```
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 1 MB. Consider using [`ReadableStream`](/workers/runtime-apis/streams/readablestream/) when returning more data.
---
# 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
Because it has not yet landed in V8, the `using` keyword is not yet available directly in the Workers runtime. To use it in your code, you must use a prerelease version of the [Wrangler CLI](/workers/wrangler/) to run and deploy your Worker:
```sh
npx wrangler@using-keyword-experimental dev
```
This version of Wrangler will transpile `using` into direct calls to `Symbol.dispose()`, before running your code or deploying it to Cloudflare.
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.
```
---
# 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`
---
# TypeScript
URL: https://developers.cloudflare.com/workers/runtime-apis/rpc/typescript/
The [`@cloudflare/workers-types`](https://www.npmjs.com/package/@cloudflare/workers-types) package provides the `Service` and `DurableObjectNamespace` types, each of which accepts a single type parameter for the server-side [`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).
For example:
```ts
interface Env {
SUM_SERVICE: Service<SumService>;
COUNTER_OBJECT: DurableObjectNamespace<Counter>
}
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">
```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">
```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)
---
# 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)
---
# 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)
---
# 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/
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:
```sh
$ npm install -D miniflare
```
## 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({
script: `
export default {
let lastScheduledController;
let lastQueueBatch;
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 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" },
{ id: "b", timestamp: new Date(2000), body: { b: 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();
// 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/
:::note
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.
:::
import { TabItem, Tabs, Details } from "~/components";
import { FileTree } from "@astrojs/starlight/components";
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:
<Tabs> <TabItem label="npm">
```sh
npm install -D miniflare
```
</TabItem> <TabItem label="yarn">
```sh
yarn add -D miniflare
```
</TabItem> <TabItem label="pnpm">
```sh
pnpm add -D miniflare
```
</TabItem> </Tabs>
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. You can use the [`defineWorkersConfig()`](/workers/testing/vitest-integration/configuration/#defineworkersconfigoptions) API for better type checking and completions.
An example configuration would be:
```ts
import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
export default defineWorkersConfig({
test: {
poolOptions: {
workers: {
wrangler: {
configPath: "./wrangler.toml"
},
},
},
},
});
```
:::note
Use [`defineWorkersProject`](#defineworkersprojectoptions) with [Vitest Workspaces](https://vitest.dev/guide/workspace) to specify a different configuration for certain tests.
:::
:::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: {
// ...
},
},
},
});
```
### `defineWorkersProject(options)`
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), except it should be used in place of the [`defineProject()`](https://vitest.dev/guide/workspace) function from Vitest.
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: {
// ...
},
},
},
}),
// ...
]);
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`: stringoptional
* 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`: booleanoptional
* 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`: booleanoptional
* 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.
:::caution
You must define a compatibility date of `2022-10-31` or higher, and include [`nodejs_compat` in your compatibility flags](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) to use the Workers Vitest integration.
:::
## `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"
>;
```
---
# Vitest integration
URL: https://developers.cloudflare.com/workers/testing/vitest-integration/
import { DirectoryListing, Render } from "~/components"
Information about the Workers Vitest integration - the recommended package for writing unit and integration tests for Workers.
<DirectoryListing />
<Render file="testing-pages-functions" product="workers" />
---
# 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.
---
# 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`.
### `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`.
### `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`.
### `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`.
## 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
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)
---
# 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.
---
# 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/setup/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: "Hello World Worker",
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:
<Tabs> <TabItem label="pnpm">
```sh
pnpm install mimetext
```
</TabItem> <TabItem label="npm">
```sh
npm install mimetext
```
</TabItem> <TabItem label="yarn">
```sh
yarn add mimetext
```
</TabItem> </Tabs>
## 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/).
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: "Hello World Worker",
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: "Hello World Worker",
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/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':
```sh title="Installing the qr-image package"
npm install --save 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.
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**.
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.
#### 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`.
### 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**.
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.
<Tabs> <TabItem label="npm">
```sh title="Run your application locally"
npm run dev
```
</TabItem> <TabItem label="yarn">
```sh title="Run your application locally"
yarn dev
```
</TabItem> </Tabs>
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:
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:
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.
<Tabs> <TabItem label="npm">
```sh title="Deploy your application"
npm run deploy
```
</TabItem> <TabItem label="yarn">
```sh title="Deploy your application"
yarn deploy
```
</TabItem> </Tabs>
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:
## 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/).
---
# 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.
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: "Hello World Worker",
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:
```sh
npm install 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:
```sh
npm install 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.
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.
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.
---
# 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/native-integrations/turso/). The Turso Database Integration will connect your Worker to a Turso database by getting the right configuration from Turso and adding it as [secrets](/workers/configuration/secrets/) to 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: "Hello World Worker",
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:
```sh
npm install @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).
---
# 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.
To continue with this tutorial, you must purchase the [Workers Paid plan](/workers/platform/pricing/#workers) and enable Durable Objects by logging into the [Cloudflare dashboard](https://dash.cloudflare.com) > **Workers & Pages** > select your Worker > **Durable Objects**.
<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_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/)
---
# Create a deploy button with GitHub Actions
URL: https://developers.cloudflare.com/workers/tutorials/deploy-button/
Deploy buttons let you deploy applications to Cloudflare's global network in under five minutes. The deploy buttons use Wrangler to deploy a Worker using the [Wrangler GitHub Action](https://github.com/marketplace/actions/deploy-to-cloudflare-workers-with-wrangler). You can deploy an application from a set of ready-made Cloudflare templates, or make deploy buttons for your own applications to make sharing your work easier.
Try the deploy button below to deploy a GraphQL server:
[](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/workers-graphql-server)
Refer to [deploy.workers.cloudflare.com](https://deploy.workers.cloudflare.com/) for additional projects to deploy.
## Create a deploy button for your project
1. Add a GitHub Actions workflow to your project.
Add a new file to `.github/workflows`, such as `.github/workflows/deploy.yml`, and create a GitHub workflow for deploying your project. It should include a set of `on` events, including at least `repository_dispatch`, but probably `push` and maybe `schedule` as well. Add a step for publishing your project using [wrangler-action](https://github.com/cloudflare/wrangler-action):
```yaml
name: Deploy Worker
on:
push:
pull_request:
repository_dispatch:
jobs:
deploy:
runs-on: ubuntu-latest
timeout-minutes: 60
needs: test
steps:
- uses: actions/checkout@v2
- name: Build & Deploy Worker
uses: cloudflare/wrangler-action@v3
with:
apiToken: ${{ secrets.CF_API_TOKEN }}
accountId: ${{ secrets.CF_ACCOUNT_ID }}
```
2. Add the Markdown code for your button to your project's README, replacing the example `url` parameter with your repository URL.
```md
[](https://deploy.workers.cloudflare.com/?url=https://github.com/YOURUSERNAME/YOURREPO)
```
3. With your button configured, anyone can use the **Deploy with Workers** button in your repository README, and deploy their own copy of your application to Cloudflare's global network.
---
# 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.
---
<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: "Hello World Worker",
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.
---
## 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 publish` command to redeploy your Worker project:
```sh
npx wrangler deploy
```
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:
Adding a query parameter with custom text, you should receive:
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: "Hello World Worker",
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/setup/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!`.
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:
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.
<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: "Hello World Worker",
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 ...
```
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:
## 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)
---
# 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: "Hello World Worker",
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:
```sh
npm install 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/).
<WranglerConfig>
```toml
DB_URL="<ENTER YOUR POSTGRESQL CONNECTION STRING>"
```
</WranglerConfig>
### 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"
```
You can also use explicit parameters by following the [wrangler documentation for Hyperdrive](/workers/wrangler/commands/#r2-bucket-create).
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.
---
# 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: "Hello World Worker",
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
```sh
npm install 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.
---
# 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.
---
## 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 --experimental"}
/>
<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: "Hello World Worker using 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_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/frameworks/framework-guides/nextjs/).
- [Build a seat booking app with SQLite in Durable Objects](/durable-objects/tutorials/build-a-seat-booking-app/).
---
# 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.
:::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`.
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.
:::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`.
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/)
---
# Create a serverless, globally distributed REST API with Fauna
URL: https://developers.cloudflare.com/workers/tutorials/store-data-with-fauna/
import { Render, TabItem, Tabs, PackageManagers, WranglerConfig } from "~/components";
In this tutorial, you learn how to store and retrieve data in your Cloudflare Workers applications by building a REST API that manages an inventory catalog using [Fauna](https://fauna.com/) as its data layer.
## Learning goals
- How to store and retrieve data from Fauna in Workers.
- How to use Wrangler to store secrets securely.
- How to use [Hono](https://hono.dev) as a web framework for your Workers.
Building with Fauna, Workers, and Hono enables you to create a globally distributed, strongly consistent, fully serverless REST API in a single repository.
Fauna is a document-based database with a flexible schema. This allows you to define the structure of your data – whatever it may be – and store documents that adhere to that structure. In this tutorial, you will build a product inventory, where each `product` document must contain the following properties:
- **title** - A human-friendly string that represents the title or name of a product.
- **serialNumber** - A machine-friendly string that uniquely identifies the product.
- **weightLbs** - A floating point number that represents the weight in pounds of the product.
- **quantity** - A non-negative integer that represents how many items of a particular product there are in the inventory.
Documents are stored in a [collection](https://docs.fauna.com/fauna/current/reference/schema_entities/collection/). Collections in document databases are groups of related documents.
For this tutorial, all API endpoints are public. However, Fauna also offers multiple avenues for securing endpoints and collections. Refer to [Choosing an authentication strategy with Fauna](https://fauna.com/blog/choosing-an-authentication-strategy-with-fauna) for more information on authenticating users to your applications with Fauna.
<Render file="tutorials-before-you-start" />
## Set up Fauna
### Create your database
To create a database, log in to the [Fauna Dashboard](https://dashboard.fauna.com/) and click **Create Database**. When prompted, select your preferred [Fauna region group](https://docs.fauna.com/fauna/current/manage/region-groups/) and other database settings.
:::note[Fauna Account]
If you do not have a Fauna account, [sign up](https://dashboard.fauna.com/register) and deploy this template using the free tier.
:::
### Create a collection
Create a `Products` collection for the database with the following query. To run the query in the Fauna Dashboard, select your database and click the **Shell** tab:
```js title="Create a new collection"
Collection.create({ name: "Products" });
```
The query outputs a result similar to the following:
```js title="Output"
{
name: "Products",
coll: Collection,
ts: Time("2099-08-28T15:03:53.773Z"),
history_days: 0,
indexes: {},
constraints: []
}
```
### Create a secret key
In production, the Worker will use the Cloudflare Fauna integration to automatically connect to Fauna. The integration creates any credentials needed for authentication with Fauna.
For local development, you must manually create a [Fauna authentication key](https://docs.fauna.com/fauna/current/learn/security/keys/) and pass the key's secret to your Worker as a [development secret](#add-your-fauna-database-key-for-local-development).
To create a Fauna authentication key:
1. In the upper left pane of Fauna Dashboard’s Explorer page, select your database, and click the **Keys** tab.
2. Click **Create Key**.
3. Choose a **Role** of **Server**.
4. Click **Save**.
5. Copy the **Key Secret**. The secret is scoped to the database.
:::caution[Protect your keys]
Server keys can read and write all documents in all collections and can call all [user-defined functions](https://docs.fauna.com/fauna/current/cookbook/data_model/user_defined_functions) (UDFs). Protect server keys and do not commit them to source control repositories.
:::
## Manage your inventory with Workers
### Create a new Worker project
Create a new project by using [C3](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare).
<PackageManagers type="create" pkg="cloudflare@latest" args={"fauna-workers"} />
To continue with this guide:
- 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`.
Then, move into your newly created directory:
```sh
cd fauna-workers
```
Update the Wrangler file to set the name for the Worker.
<WranglerConfig>
```toml title="wrangler.toml"
name = "fauna-workers"
```
</WranglerConfig>
### Add your Fauna database key for local development
For local development, add a `.dev.vars` file on the project root and add your Fauna key's secret as a [development secret](/workers/configuration/secrets/#local-development-with-secrets):
```plain title=".dev.vars"
DATABASE_KEY=<FAUNA_SECRET>
```
### Add the Fauna integration
Deploy your Worker to Cloudflare to ensure that everything is set up correctly:
```sh
npm run deploy
```
1. Login to your [Cloudflare dashboard](https://dash.cloudflare.com/).
2. Select the **Integrations** tab and click on the **Fauna** integration.
3. Login to your Fauna account.
4. Select the Fauna database you created earlier.
5. Select `server` role as your database role.
6. Enter `DATABASE_KEY` as the **Secret Name**.
7. Select **Finish**.
8. Navigate to **Settings** tab and select **Variables**. Notice that a new variable `DATABASE_KEY`
is added to your Worker.
The integration creates a new Fauna authentication key and stores the key's secret in the Worker's `DATABASE_KEY` secret. The deployed Worker uses this key.
:::note
You can manage the generated Fauna key in the Fauna Dashboard. See the [Clouflare Fauna integration docs](/workers/databases/native-integrations/fauna).
:::
### Install dependencies
Install [the Fauna JavaScript driver](https://github.com/fauna/fauna-js) in your newly created Worker project.
<Tabs> <TabItem label="npm">
```sh title="Install the Fauna driver"
npm install fauna
```
</TabItem> <TabItem label="yarn">
```sh title="Install the Fauna driver"
yarn add fauna
```
</TabItem> </Tabs>
### Base inventory logic
Replace the contents of your `src/index.ts` file with the skeleton of your API:
```ts title="src/index.ts"
import { Hono } from "hono";
import { Client, fql, ServiceError } from "fauna";
type Bindings = {
DATABASE_KEY: string;
};
type Variables = {
faunaClient: Client;
};
type Product = {
id: string;
serialNumber: number;
title: string;
weightLbs: number;
quantity: number;
};
const app = new Hono<{ Bindings: Bindings; Variables: Variables }>();
app.use("*", async (c, next) => {
const faunaClient = new Client({
secret: c.env.DATABASE_KEY,
});
c.set("faunaClient", faunaClient);
await next();
});
app.get("/", (c) => {
return c.text("Hello World");
});
export default app;
```
This is custom middleware to initialize the Fauna client and set the instance with `c.set()` for later use in another handler:
```js title="Custom middleware for the Fauna Client"
app.use("*", async (c, next) => {
const faunaClient = new Client({
secret: c.env.DATABASE_KEY,
});
c.set("faunaClient", faunaClient);
await next();
});
```
You can access the `DATABASE_KEY` environment variable from `c.env.DATABASE_KEY`. Workers run on a [custom JavaScript runtime](/workers/runtime-apis/) instead of Node.js, so you cannot use `process.env` to access your environment variables.
### Create product documents
Add your first Hono handler to the `src/index.ts` file. This route accepts `POST` requests to the `/products` endpoint:
```ts title="Create product documents"
app.post("/products", async (c) => {
const { serialNumber, title, weightLbs } =
await c.req.json<Omit<Product, "id">>();
const query = fql`Products.create({
serialNumber: ${serialNumber},
title: ${title},
weightLbs: ${weightLbs},
quantity: 0
})`;
const result = await c.var.faunaClient.query<Product>(query);
return c.json(result.data);
});
```
:::caution[Handler order]
In Hono, you should place your handler below the custom middleware.
This is because middleware and handlers are executed in sequence from top to bottom.
If you place the handler first, you cannot retrieve the instance of the Fauna client using `c.var.faunaClient`.
:::
This route applied an FQL query in the `fql` function that creates a new document in the **Products** collection:
```js title="Create query in FQL inside JavaScript"
fql`Products.create({
serialNumber: ${serialNumber},
title: ${title},
weightLbs: ${weightLbs},
quantity: 0
})`;
```
To review what a document looks like, run the following query. In the Fauna dashboard, go to **Explorer** > Region name > Database name like a `cloudflare_rest_api` > the **SHELL** window:
```js title="Create query in pure FQL"
Products.create({
serialNumber: "A48432348",
title: "Gaming Console",
weightLbs: 5,
quantity: 0,
});
```
Fauna returns the created document:
```js title="Newly created document"
{
id: "<document_id>",
coll: Products,
ts: "<timestamp>",
serialNumber: "A48432348",
title: "Gaming Console",
weightLbs: 5,
quantity: 0
}
```
Examining the route you create, when the query is successful, the data newly created document is returned in the response body:
```js title="Return the new document data"
return c.json({
productId: result.data,
});
```
### Error handling
If Fauna returns any error, an exception is raised by the client. You can catch this exception in `app.onError()`, then retrieve and respond with the result from the instance of `ServiceError`.
```ts title="Handle errors"
app.onError((e, c) => {
if (e instanceof ServiceError) {
return c.json(
{
status: e.httpStatus,
code: e.code,
message: e.message,
},
e.httpStatus,
);
}
console.trace(e);
return c.text("Internal Server Error", 500);
});
```
### Retrieve product documents
Next, create a route that reads a single document from the **Products** collection.
Add the following handler to your `src/index.ts` file. This route accepts `GET` requests at the `/products/:productId` endpoint:
```ts title="Retrieve product documents"
app.get("/products/:productId", async (c) => {
const productId = c.req.param("productId");
const query = fql`Products.byId(${productId})`;
const result = await c.var.faunaClient.query<Product>(query);
return c.json(result.data);
});
```
The FQL query uses the [`byId()`](https://docs.fauna.com/fauna/current/reference/schema_entities/collection/instance-byid) method to retrieve a full document from the **Productions** collection:
```js title="Retrieve a document by ID in FQL inside JavaScript"
fql`Products.byId(productId)`;
```
If the document exists, return it in the response body:
```ts title="Return the document in the response body"
return c.json(result.data);
```
If not, an error is returned.
### Delete product documents
The logic to delete product documents is similar to the logic for retrieving products. Add the following route to your `src/index.ts` file:
```ts title="Delete product documents"
app.delete("/products/:productId", async (c) => {
const productId = c.req.param("productId");
const query = fql`Products.byId(${productId})!.delete()`;
const result = await c.var.faunaClient.query<Product>(query);
return c.json(result.data);
});
```
The only difference from the previous route is that you use the [`delete()`](https://docs.fauna.com/fauna/current/reference/auth/key/delete) method, combined with the `byId()` method, to delete a document.
When the delete operation is successful, Fauna returns the deleted document and the route forwards the deleted document in the response's body. If not, an error is returned.
## Test and deploy your Worker
Before deploying your Worker, test it locally by using Wrangler's [`dev`](/workers/wrangler/commands/#dev) command:
<Tabs> <TabItem label="npm">
```sh title="Develop your Worker"
npm run dev
```
</TabItem> <TabItem label="yarn">
```sh title="Develop your Worker"
yarn dev
```
</TabItem> </Tabs>
Once the development server is up and running, start making HTTP requests to your Worker.
First, create a new product:
```sh title="Create a new product"
curl \
--data '{"serialNumber": "H56N33834", "title": "Bluetooth Headphones", "weightLbs": 0.5}' \
--header 'Content-Type: application/json' \
--request POST \
http://127.0.0.1:8787/products
```
You should receive a `200` response similar to the following:
```json title="Create product response"
{
"productId": "<document_id>"
}
```
:::note
Copy the `productId` value for use in the remaining test queries.
:::
Next, read the document you created:
```sh title="Read a document"
curl \
--header 'Content-Type: application/json' \
--request GET \
http://127.0.0.1:8787/products/<document_id>
```
The response should be the new document serialized to JSON:
```json title="Read product response"
{
"coll": {
"name": "Products"
},
"id": "<document_id>",
"ts": {
"isoString": "<timestamp>"
},
"serialNumber": "H56N33834",
"title": "Bluetooth Headphones",
"weightLbs": 0.5,
"quantity": 0
}
```
Finally, deploy your Worker using the [`wrangler deploy`](/workers/wrangler/commands/#deploy) command:
<Tabs> <TabItem label="npm">
```sh title="Deploy your Worker"
npm run deploy
```
</TabItem> <TabItem label="yarn">
```sh title="Deploy your Worker"
yarn deploy
```
</TabItem> </Tabs>
This publishes the Worker to your `*.workers.dev` subdomain.
## Update inventory quantity
As the last step, implement a route to update the quantity of a product in your inventory, which is `0` by default.
This will present a problem. To calculate the total quantity of a product, you first need to determine how many items there currently are in your inventory. If you solve this in two queries, first reading the quantity and then updating it, the original data might change.
Add the following route to your `src/index.ts` file. This route responds to HTTP `PATCH` requests on the `/products/:productId/add-quantity` URL endpoint:
```ts title="Update inventory quantity"
app.patch("/products/:productId/add-quantity", async (c) => {
const productId = c.req.param("productId");
const { quantity } = await c.req.json<Pick<Product, "quantity">>();
const query = fql`Products.byId(${productId}){ quantity : .quantity + ${quantity}}`;
const result =
await c.var.faunaClient.query<Pick<Product, "quantity">>(query);
return c.json(result.data);
});
```
Examine the FQL query in more detail:
```js title="Update query in FQL inside JavaScript"
fql`Products.byId(${productId}){ quantity : .quantity + ${quantity}}`;
```
:::note[Consistency guarantees in Fauna]
Even if multiple Workers update this quantity from different parts of the world, Fauna guarantees the consistency of the data across all Fauna regions. This article on [consistency](https://fauna.com/blog/consistency-without-clocks-faunadb-transaction-protocol?utm_source=Cloudflare&utm_medium=referral&utm_campaign=Q4_CF_2021) explains how Fauna's distributed protocol works without the need for atomic clocks.
:::
Test your update route:
```sh title="Update product inventory"
curl \
--data '{"quantity": 5}' \
--header 'Content-Type: application/json' \
--request PATCH \
http://127.0.0.1:8787/products/<document_id>/add-quantity
```
The response should be the entire updated document with five additional items in the quantity:
```json title="Update product response"
{
"quantity": 5
}
```
Update your Worker by deploying it to Cloudflare.
<Tabs> <TabItem label="npm">
```sh title="Update your Worker in Cloudflare"
npm run deploy
```
</TabItem> <TabItem label="yarn">
```sh title="Update your Worker in Cloudflare"
yarn deploy
```
</TabItem> </Tabs>
---
# Set up and use a Prisma Postgres database
URL: https://developers.cloudflare.com/workers/tutorials/using-prisma-postgres-with-workers/
[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:
```sh
npm install prisma --save-dev
```
Install the [Prisma Accelerate client extension](https://www.npmjs.com/package/@prisma/extension-accelerate) as it is required for Prisma Postgres:
```sh
npm install @prisma/extension-accelerate
```
Install the [`dotenv-cli` package](https://www.npmjs.com/package/dotenv-cli) to load environment variables from `.dev.vars`:
```sh
npm install dotenv-cli --save-dev
```
### 2.2. Create a Prisma Postgres database and initialize Prisma
Initialize Prisma in your application:
```sh
npx prisma@latest 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.
---
# 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: "Hello World Worker",
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.
---
# 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/).
---
# Migrations
URL: https://developers.cloudflare.com/workers/wrangler/migration/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# 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.
---
# 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 7 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 2 minutes and most checks complete in the first 4 hours. The check back off is capped to a maximum of 4 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. |
---
# 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.
---
# 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 />
---
# 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**.
---
# 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 />
---
# 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={{ one: "BigCommerce" }} />
## Benefits
<Render file="provider-guide-benefits" params={{ one: "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={{ one: "BigCommerce" }} />
---
# 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={{ one: "HubSpot" }} />
## Benefits
<Render file="provider-guide-benefits" params={{ one: "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/setup/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={{ one: "HubSpot" }} />
---
# Provider guides
URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/provider-guides/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# 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={{ one: "Kinsta" }} />
## Benefits
<Render file="provider-guide-benefits" params={{ one: "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={{ one: "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={{ one: "Salesforce Commerce Cloud" }}
/>
## Benefits
<Render
file="provider-guide-benefits"
params={{ one: "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={{ one: "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={{ one: "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/).
## 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 |
:::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={{ one: "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={{ one: "WP Engine" }} />
## Benefits
<Render file="provider-guide-benefits" params={{ one: "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" />
## Additional support
<Render file="provider-guide-help" params={{ one: "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).
---
# 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/).
<Details header="Restrict cipher suites for zone">
Refer to [Edit zone setting](/api/resources/zones/subresources/settings/methods/edit/) and use `ciphers` as the setting name in the URI path.
</Details>
<Details header="Restrict cipher suites for custom hostname">
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" />
---
# 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" />
---
# 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 />
---
# WAF for SaaS
URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/waf-for-saas/
[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:
```bash
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames" \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
--header "Content-Type: application/json" \
--data '{"Hostname":"example.com"}, "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/setup/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:
```bash
curl "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames" \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>"
```
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:
```bash
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 '{
"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.
```bash
curl --request PUT \
"https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/phases/http_ratelimit/entrypoint" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
"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\""
}
]
}'
```
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).
---
# 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:
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/).
:::
---
# 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:
* You have purchased the [Cloudflare for SaaS Enterprise plan](/cloudflare-for-platforms/cloudflare-for-saas/plans/) and the feature is properly entitled to your account.
* 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.
* 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
---
# Advanced Settings
URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# 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**.
---
# 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, install [`@cloudflare/workers-types`](https://www.npmjs.com/package/@cloudflare/workers-types) and create a [TypeScript declaration file](https://www.typescriptlang.org/docs/handbook/2/type-declarations.html).
Install Workers Types:
```sh
npm install --save-dev @cloudflare/workers-types
```
Add Workers Types to your `tsconfig.json` file, replacing the date below with your project's [compatibility date](/workers/configuration/compatibility-dates/):
```diff title="tsconfig.json"
"types": [
+ "@cloudflare/workers-types/2024-07-29"
]
```
Create an `env.d.ts` file in the root directory of your Next.js app, and explicitly declare the type of each binding:
```ts title="env.d.ts"
interface CloudflareEnv {
MY_KV_1: KVNamespace;
MY_KV_2: KVNamespace;
MY_R2: R2Bucket;
MY_DO: DurableObjectNamespace;
}
```
## 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](https://developers.cloudflare.com/workers/frameworks/), 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"
/>
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):
```sh
npm install --save-dev @cloudflare/next-on-pages
```
### 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:
```sh
npm run 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.
```sh
npm install --save-dev eslint-plugin-next-on-pages
```
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 may want to 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.
Refer to the [OpenNext docs](https://opennext.js.org/cloudflare) and the [Workers vs. Pages compatibility matrix](/workers/static-assets/compatibility-matrix/) for more information to help you decide whether Workers or Pages currently fits best for your Next.js app.
:::
<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.
---
# 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.
:::
---
# 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/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/).
---
# Use fetch() handler
URL: https://developers.cloudflare.com/workers-ai/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/function-calling/embedded/examples/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# Use KV API
URL: https://developers.cloudflare.com/workers-ai/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
```
---
# Tools based on OpenAPI Spec
URL: https://developers.cloudflare.com/workers-ai/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>;
```
---
# 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 to a selected branch.
## Features
Beyond automatic builds and deployments, the Cloudflare GitHub integration lets you monitor builds directly in GitHub, keeping you informed without leaving your workflow.
:::note[Upcoming features]
In Beta, Workers Builds supports automatic builds and deployments only from a single selected branch (e.g. `main`).
Support for building and deploying preview versions from multiple branches will be added soon, along with the ability to generate [Preview URLs](/workers/configuration/previews/) for pull requests (PRs).
:::
### 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.
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.
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.
#### 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 to a selected branch.
## Features
Beyond automatic builds and deployments, the Cloudflare GitLab integration lets you monitor builds directly in GitLab, keeping you informed without leaving your workflow.
:::note[Upcoming features]
In Beta, Workers Builds supports automatic builds and deployments only from a single selected branch (e.g. `main`).
Support for building and deploying preview versions from multiple branches will be added soon, along with the ability to generate [Preview URLs](/workers/configuration/previews/) for pull requests (PRs).
:::
### 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.
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.
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 to a selected branch.
Adding a Git integration also lets you monitor build statuses directly in your Git provider using [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.
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
You can manage the Git installation associated with your repository connection by navigating to the Worker, 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](/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 js 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.new(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);
},
};
```
---
# 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 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
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:
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)
---
# 📅 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",
],
});
```
---
# 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" />
---
# 📨 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" />
---
# 📚 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"] },
];
```
---
# Developing
URL: https://developers.cloudflare.com/workers/testing/miniflare/developing/
import { DirectoryListing } from "~/components";
<DirectoryListing path="/developing" />
---
# â¬†ï¸ 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)
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.
---
# Migrations
URL: https://developers.cloudflare.com/workers/testing/miniflare/migrations/
import { DirectoryListing } from "~/components";
<DirectoryListing />
---
# 🛠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.
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**.
With the new configuration selected, click the green debug button to start
debugging.
## 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.
---
# 🕸 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.
---
# âš¡ï¸ 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" },
});
},
};
```
---
# âœ‰ï¸ 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!"
```
---
# 🚥 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
```
---
# â° 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 }
```
---
# ✨ 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
```
---
# Get started
URL: https://developers.cloudflare.com/workers/testing/vitest-integration/get-started/
import { DirectoryListing } 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.
Get started with one of the available guides:
<DirectoryListing />
:::caution
The Workers Vitest integration does not support testing Workers using the service worker format. [Migrate to the ES modules format](/workers/reference/migrate-to-module-workers/) to use the Workers Vitest integration.
:::
---
# Migrate from Miniflare 2's test environments
URL: https://developers.cloudflare.com/workers/testing/vitest-integration/get-started/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": [
"@cloudflare/workers-types/experimental"
- "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/get-started/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/get-started/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/get-started/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/get-started/write-your-first-test/#define-types) - Write unit tests against Workers.
---
# Write your first test
URL: https://developers.cloudflare.com/workers/testing/vitest-integration/get-started/write-your-first-test/
import { TabItem, Tabs } from "~/components";
This guide will instruct you through installing and setting up the `@cloudflare/vitest-pool-workers` package. This will help you get started writing tests against your Workers using Vitest. The `@cloudflare/vitest-pool-workers` package 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). For examples of tests using `@cloudflare/vitest-pool-workers`, refer to [Recipes](/workers/testing/vitest-integration/recipes/).
## Prerequisites
- Open the root directory of your Worker or [create a new Worker](/workers/get-started/guide/#1-create-a-new-worker-project).
- Make sure that your Worker is developed using the ES modules format. To migrate from the service worker format to the ES modules format, refer to the [Migrate to the ES modules format](/workers/reference/migrate-to-module-workers/) guide.
- In your project's [Wrangler configuration file](/workers/wrangler/configuration/), define a [compatibility date](/workers/configuration/compatibility-dates/) of `2022-10-31` or higher, and include `nodejs_compat` in your [compatibility flags](/workers/configuration/compatibility-flags).
## Install Vitest and `@cloudflare/vitest-pool-workers`
Open a terminal window and make sure you are in your project's root directory. Once you have confirmed that, run:
```sh
npm install vitest@~3.0.0 --save-dev --save-exact
npm install @cloudflare/vitest-pool-workers --save-dev
```
The above commands will add the packages to your `package.json` file and install them as dev dependencies.
:::note
Currently, the `@cloudflare/vitest-pool-workers` package _only_ works with Vitest 2.0.x - 3.0.x.
:::
## Define Vitest configuration
If you do not already have a `vitest.config.js` or `vitest.config.ts` file, you will need to create one and define the following configuration.
You can reference a Wrangler file to leverage its `main` entry point, [compatibility settings](/workers/configuration/compatibility-dates/), and [bindings](/workers/runtime-apis/bindings/).
```js
import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
export default defineWorkersConfig({
test: {
poolOptions: {
workers: {
wrangler: { configPath: "./wrangler.toml" },
},
},
},
});
```
:::note
For a full list of available configuration options, refer to [Configuration](/workers/testing/vitest-integration/configuration/).
:::
### Add configuration options via Miniflare
Under the hood, the Workers Vitest integration uses [Miniflare](https://miniflare.dev), the same simulator that powers [`wrangler dev`'s](/workers/wrangler/commands/#dev) local mode. Options can be passed directly to Miniflare for advanced configuration.
For example, to add bindings that will be used in tests, you can add `miniflare` to `defineWorkersConfig`:
```js null {6-8}
export default defineWorkersConfig({
test: {
poolOptions: {
workers: {
main: "./src/index.ts",
miniflare: {
kvNamespaces: ["TEST_NAMESPACE"],
},
},
},
},
});
```
This configuration would add a KV namespace `TEST_NAMESPACE` that was only accessible in tests. Using this method, you can add or override existing bindings like Durable Objects or service bindings.
:::note
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).
:::
## Define types
If you are using TypeScript, you will need to define types for Cloudflare Workers and `cloudflare:test` to make sure they are detected appropriately. Add a `tsconfig.json` in the same folder as your tests (that is, `test`) and add the following:
```js
{
"extends": "../tsconfig.json",
"compilerOptions": {
"moduleResolution": "bundler",
"types": [
"@cloudflare/workers-types/experimental",
"@cloudflare/vitest-pool-workers"
]
},
"include": ["./**/*.ts", "../src/env.d.ts"]
}
```
Save this file, and you are ready to write your first test.
## Write tests
If you created a basic Worker via the guide listed above, you should have the following fetch handler in the `src` folder:
<Tabs> <TabItem label="JavaScript" icon="seti:javascript">
```js
export default {
async fetch(request, env, ctx) {
return new Response("Hello World!");
},
};
```
</TabItem> <TabItem label="TypeScript" icon="seti:typescript">
```ts
export default {
async fetch(request, env, ctx): Promise<Response> {
return new Response("Hello World!");
},
} satisfies ExportedHandler<Env>;
```
</TabItem> </Tabs>
This Worker receives a request, and returns a response of `"Hello World!"`. In order to test this, create a `test` folder with the following test file:
<Tabs> <TabItem label="JavaScript" icon="seti:javascript">
```js
import {
env,
createExecutionContext,
waitOnExecutionContext,
} from "cloudflare:test";
import { describe, it, expect } from "vitest";
// Could import any other source file/function here
import worker from "../src";
describe("Hello World worker", () => {
it("responds with Hello World!", async () => {
const request = new Request("http://example.com");
// 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.text()).toBe("Hello World!");
});
});
```
</TabItem> <TabItem label="TypeScript" icon="seti:typescript">
```ts
import {
env,
createExecutionContext,
waitOnExecutionContext,
} from "cloudflare:test";
import { describe, it, expect } from "vitest";
// Could import any other source file/function here
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");
// 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.text()).toBe("Hello World!");
});
});
```
</TabItem> </Tabs>
Add functionality to handle a `404` path on the Worker. This functionality will return the text `Not found` as well as the status code `404`.
<Tabs> <TabItem label="JavaScript" icon="seti:javascript">
```js
export default {
async fetch(request, env, ctx) {
const { pathname } = new URL(request.url);
if (pathname === "/404") {
return new Response("Not found", { status: 404 });
}
return new Response("Hello World!");
},
};
```
</TabItem> <TabItem label="TypeScript" icon="seti:typescript">
```ts
export default {
async fetch(request, env, ctx): Promise<Response> {
const { pathname } = new URL(request.url);
if (pathname === "/404") {
return new Response("Not found", { status: 404 });
}
return new Response("Hello World!");
},
} satisfies ExportedHandler<Env>;
```
</TabItem> </Tabs>
To test this, add the following to your test file:
<Tabs> <TabItem label="JavaScript" icon="seti:javascript">
```js
it("responds with not found and proper status for /404", async () => {
const request = new Request("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");
});
```
</TabItem> <TabItem label="TypeScript" icon="seti:typescript">
```ts
it("responds with not found and proper status for /404", 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");
});
```
</TabItem> </Tabs>
## Related resources
- [`@cloudflare/vitest-pool-workers` GitHub repository](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples) - Examples of tests using the `@cloudflare/vitest-pool-workers` package.
---
# 1. Migrate webpack projects
URL: https://developers.cloudflare.com/workers/wrangler/migration/v1-to-v2/eject-webpack/
import { WranglerConfig } 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:
```
npm install --save-dev webpack@^4.46.0 webpack-cli wranglerjs-compat-webpack-plugin
# or
yarn add --dev webpack@4.46.0 webpack-cli wranglerjs-compat-webpack-plugin
```
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 />
---
# 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 } 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.
---
# 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.
---
# 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.
---
# 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" />
---
# 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 />
---
# 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 proxying traffic through Cloudflare 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 proxying traffic through Cloudflare, 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 proxying traffic through Cloudflare, 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
<Render file="txt-validation_preamble" /> <br/>
<Render file="update-dcv-method" /> <br/>
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/).
---
# 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" />
---
# 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
```
---
# 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
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>
---
# 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 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)
```
---
# 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 />
---
# 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
```
---
# 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.
***
## When to use
### HTTP DCV
<Render file="http-dcv-situation" />
### TXT DCV
<Render file="txt-dcv-situation" /> <br/>
* [DCV Delegation](#setup) (generally recommended)
* [Manual](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/txt/)
***
## 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/setup/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.
---
# 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>`: An absolute path on the origin server or 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.
### `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 40MB. Contact Stream if the input limitation is unacceptable.
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.
---
# React
URL: https://developers.cloudflare.com/workers/frameworks/framework-guides/react/
import {
Badge,
Description,
InlineBadge,
Render,
PackageManagers,
} from "~/components";
In this guide, you will create a new [React](https://react.dev/) application and deploy to Cloudflare Workers (with the new [<InlineBadge preset="beta" /> 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 React template, and provide the option to deploy instantly.
To use `create-cloudflare` to create a new React project with <InlineBadge preset="beta" /> Workers Assets, run the following command:
<PackageManagers
type="create"
pkg="cloudflare@latest my-react-app"
args={"--framework=react --platform=workers"}
/>
<Render
file="c3-post-run-steps"
product="workers"
params={{
category: "web-framework",
framework: "React",
}}
/>
After setting up your project, change your directory by running the following command:
```sh
cd my-react-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 are using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.
<PackageManagers type="run" args={"deploy"} />
---
## Static assets
You can serve static assets in your React application by [placing them in the `./public/` directory](https://vite.dev/guide/assets#the-public-directory). This can be useful for resource files such as images, stylesheets, fonts, and manifests.
<Render file="workers-assets-routing-summary" />
---