Build it. Deploy it. Understand it.

A tiny Worker API example

This example returns a JSON health response. It is a learning example, not a complete production API.

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

    if (url.pathname === "/api/health") {
      return Response.json({ status: "ok" });
    }

    return new Response("Not found", { status: 404 });
  }
};

The env argument provides configured bindings and secrets. The example does not use it yet. A real API may need authentication, authorization, input validation, rate limits, safe error handling and logging that avoids sensitive data.

Deploy static assets with Workers

For the CLI workflow, Cloudflare provides a project starter. One common starting command is:

npm create cloudflare@latest -- my-static-site

Follow the prompts and select a static-site or suitable full-stack starter. For an existing project, follow the current Workers Static Assets instructions and point the asset directory at the actual deployable files. Use npx wrangler dev to test locally and npx wrangler deploy when the project is configured and ready. Exact setup depends on the starter and its Wrangler configuration.

Storage and data options

• D1: managed SQL database.
• KV: key-value storage for suitable lookup patterns.
• R2: object/file storage.
• Queues: asynchronous work processing.
• Durable Objects: stateful coordination and suitable real-time workloads.
• External database: an option when the provider and connection model suit the app.

These resources are not automatically created just because you deploy a Worker. Create the resource, configure its binding securely, and design access permissions and data handling.

Official references: Workers Static Assets ↗ · Workers secrets ↗ · Pages Functions ↗

Connect a custom domain

1. Own the domain or have permission from its owner.
2. Open the relevant Pages project or Worker and find custom-domain settings.
3. Add the exact hostname, such as www.example.com or example.com.
4. Follow the DNS instructions shown for that project and wait for validation/certificate setup.
5. Test HTTPS and decide which hostname should be canonical.

Do not delete DNS records just to make the website work. MX, SPF, DKIM and DMARC records may be needed for business email. DNS changes can affect services other than the website.

Security checklist

These checkboxes are a local checklist for your browser; they do not change Cloudflare settings. For payment or personal-data systems, use a proper security review and follow applicable laws and provider requirements.

Troubleshooting common errors

A. Before you configure routing

1. Add your domain to Cloudflare and use Cloudflare as its authoritative DNS provider. Email Service routing requires Cloudflare DNS.
2. Decide which addresses you need, such as hello@yourdomain.com, support@yourdomain.com, sales@yourdomain.com and billing@yourdomain.com.
3. Choose an existing mailbox that will receive forwarded messages, and make sure you can open and verify it.
4. Inspect existing DNS records first. If the domain already uses Google Workspace, Microsoft 365 or another email provider, do not replace its MX records blindly.

B. Configure Cloudflare Email Service / Email Routing

1. Open the Cloudflare dashboard and go to Compute → Email Service → Email Routing (the dashboard label may change).
2. Choose the domain and start onboarding. Review the DNS records Cloudflare proposes to add, including the MX and relevant authentication records.
3. Open Destination Addresses, add the inbox where you want to receive forwarded messages, and click the verification link sent to that mailbox.
4. Create a custom address and choose the verified destination. Repeat for other addresses if needed.
5. Send a test message from an unrelated email account. Confirm delivery to the destination inbox and check spam/junk if it does not arrive.
6. Review routing analytics and troubleshoot DNS or verification warnings shown by Cloudflare.

Official setup: Route emails with Cloudflare Email Service ↗ · Email Service documentation ↗

C. DNS records in simple terms

D. Can I send email from my website?

Incoming forwarding and outbound email are separate. A contact form, password reset, receipt or booking confirmation needs a sending service or a supported email API. Cloudflare Email Service includes sending capabilities, but you must configure the domain and sending workflow according to its current documentation. A third-party provider is also an option.

• Keep API keys and provider credentials in Worker secrets or your backend's secret manager, never in browser JavaScript.
• Validate form input on the server and add rate limiting, abuse protection and sensible message limits.
• Use a verified sender domain and correctly configured SPF/DKIM/DMARC as instructed by the provider.
• Handle delivery failures gracefully and avoid exposing whether a private account exists in password-reset flows.
• Test delivery to multiple providers and check spam placement, not just the success response from an API.

Useful references: Cloudflare Email Service ↗ · Cloudflare DNS ↗

Create your first bucket

1. Open the Cloudflare dashboard and select R2 Object Storage. If asked, enable R2 for the account and review the current pricing and storage/operation allowances.
2. Select Create bucket. Choose a clear name such as christech-public-assets-dev for development. Use separate buckets or clearly separated policies for production and private uploads.
3. Choose the location options offered by the dashboard where applicable, and create the bucket.
4. Open the bucket and upload a harmless test image or text file. Check its object key and metadata. Object keys are paths/names inside the bucket; they are not necessarily ordinary folders.
5. Decide how your application will access objects: a Worker binding for server-side access, a presigned URL for temporary access, or a deliberately public custom domain for public assets.

Option A: use R2 from a Worker

1. Create or open your Worker project and install/configure Wrangler using the current Cloudflare instructions.
2. Add an R2 bucket binding in your Wrangler configuration. For example, the binding name might be ASSETS; your code then accesses env.ASSETS. Use the exact bucket name and configuration generated for your project.
3. In the Worker, use the binding to put, get, list or delete objects only after validating the request and checking the caller's permissions.
4. For uploads, enforce file-size limits, permitted content types, safe filenames/object keys and authorization. Do not trust a filename or MIME type supplied by the browser.
5. Test with a small file locally, deploy to a development environment, then test upload, download, overwrite and unauthorized access before production.

// Illustrative Worker pattern — add the matching R2 binding first.
export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    if (url.pathname === "/health") {
      return Response.json({ ok: true });
    }
    if (url.pathname === "/example-file" && request.method === "GET") {
      const object = await env.ASSETS.get("demo/hello.txt");
      if (!object) return new Response("Not found", { status: 404 });
      return new Response(object.body, {
        headers: { "Content-Type": object.httpMetadata?.contentType || "text/plain" }
      });
    }
    return new Response("Not found", { status: 404 });
  }
};

This example assumes a binding called ASSETS exists and an object called demo/hello.txt has been uploaded. It is not a public upload endpoint and should not be mistaken for a complete file manager.

Option B: share a file with a presigned URL

1. Keep the bucket private.
2. Use the supported S3-compatible API or SDK from trusted server-side code to create a time-limited presigned URL.
3. Give the URL only to the authorized person and keep its expiry short enough for the use case.
4. Remember that anyone who obtains the URL can generally use it until it expires. Do not log or publish sensitive presigned URLs.

Option C: serve public files

1. Only use public access for content that is genuinely intended for everyone, such as public product images or static downloads.
2. For testing, Cloudflare provides an r2.dev development URL, but it is rate-limited and intended for non-production use.
3. For production, connect a domain you control using the R2 custom-domain workflow, then test HTTPS, cache behavior and object paths.
4. Do not assume enabling a public bucket creates a browsable file listing at the root. Link to exact object paths.

R2 CORS, uploads and safety

• CORS: configure allowed origins, methods and headers only when a browser needs cross-origin access. CORS is not authentication.
• Large uploads: consider direct-to-R2 uploads using short-lived presigned URLs rather than proxying every large file through a Worker.
• Private documents: keep the bucket private and check authorization before issuing a download URL.
• Lifecycle and cleanup: define a retention policy for temporary uploads and abandoned files.
• Backups: test restoration. A copy in the same account may not protect against every deletion or account-level incident.
• Costs: review storage, operations, egress and applicable plan limits in the current pricing page.

Official guides: R2 quick start ↗ · Public buckets ↗ · Presigned URLs ↗ · R2 CORS ↗

AI Gateway: observe and manage AI requests

AI Gateway sits between your application and supported AI providers. It can provide analytics, request logging, caching, rate limiting, retries and related controls. It does not magically make every provider free, and it does not replace your application's authorization.

1. Open AI Gateway in the Cloudflare dashboard and create a gateway with a recognizable name, such as christech-learning.
2. Choose the provider and model your application already uses, or follow the gateway's current integration instructions for the provider.
3. Update the server-side API URL/SDK configuration to route requests through that gateway. Keep provider API keys in Worker secrets or another server-side secret manager.
4. Send a small test prompt and verify that the request appears in the gateway's analytics/logs.
5. Enable caching only for requests where reuse is safe and appropriate. Be careful with personalized prompts, private data and responses that must always be fresh.
6. Set appropriate rate limits and retry behavior. Avoid retry storms, duplicated billable requests and overly generous limits for anonymous users.
7. Monitor request volume, tokens, errors and costs. Check log retention and privacy settings before sending personal or confidential data.

Official guide: AI Gateway overview ↗ · AI Gateway pricing and logging ↗

Workers AI: run supported AI models

Workers AI lets your Worker call models available in Cloudflare's model catalog without you managing a GPU server. Model availability, context sizes, features, quotas and pricing can change, so check the current catalog before choosing a model.

1. Create a Worker project using the Cloudflare starter or open your existing Worker project.
2. In the Wrangler configuration, add the Workers AI binding using the documented name (many examples use AI).
3. Call the chosen model from server-side Worker code through env.AI, following the model's required input and output schema.
4. Test with a short, non-sensitive prompt and handle errors, timeouts, invalid model output and usage limits.
5. Put authentication and per-user usage controls in front of public AI endpoints so anonymous visitors cannot consume unlimited resources.
6. Evaluate model quality for your actual task and language. Do not assume an AI answer is factually correct; validate important outputs and disclose limitations to users.
7. Deploy, test under expected traffic and monitor usage and costs.

Official guide: Workers AI getting started ↗ · Workers AI with Wrangler ↗

Vectorize: semantic search and retrieval

Vectorize is a vector database. An embedding model turns text or other supported inputs into arrays of numbers that represent semantic features. Vectorize stores and searches those vectors; it does not automatically store or secure all of the original documents for you.

1. Decide what you need to search: product descriptions, help articles, course notes or documents.
2. Choose an embedding model and create a Vectorize index with the model's exact vector dimensions and a suitable similarity metric. Those index settings are fixed, so verify them before creating the production index.
3. Add the Vectorize binding and Workers AI binding to your Worker configuration.
4. Prepare clean source content and stable IDs. Generate embeddings for each document and upsert vectors with useful metadata.
5. For a search, embed the user's query using the same compatible embedding model and query the index for nearest matches.
6. Fetch the matched source text from an authorized database or object store, filter by the user's permissions, and then use the selected context in your application.
7. Evaluate relevance, stale-content removal, duplicate documents, metadata filters and access-control boundaries. Never let a vector match bypass document permissions.

For retrieval-augmented generation (RAG), the common flow is: user question → query embedding → vector search → permission-filtered source passages → model prompt → answer with source references. Keep the original sources so the answer can be checked.

Official guide: Vectorize getting started ↗ · Vectorize with Workers AI embeddings ↗

A sensible AI application architecture

1. The browser calls your authenticated Worker endpoint.
2. The Worker validates the user, request size, permissions and rate limits.
3. AI Gateway routes supported provider traffic and provides monitoring controls; Workers AI can run supported Cloudflare-hosted models.
4. Vectorize can retrieve relevant passages if your app needs semantic search.
5. D1 or R2 can store application records and original documents according to their access requirements.
6. The Worker returns a safe response and logs only what is necessary.