How to Use Cloudflare Workers: The Beginner's Guide (First Worker, Wrangler, and a Live URL)

CodexFuse Team · 2026-11-03T10:58:02.373Z · 10 min read min read

From zero to a live URL in fifteen minutes: scaffold with C3, test locally with wrangler dev, deploy to workers.dev, and wire up routes, secrets, and the free tier.

How to Use Cloudflare Workers: The Beginner's Guide (First Worker, Wrangler, and a Live URL)

Learning how to use Cloudflare Workers is one of the fastest ways a developer can ship real code to the internet — and this Cloudflare Workers for beginners guide takes you from zero to a live URL in about fifteen minutes. Workers is Cloudflare's serverless platform for running JavaScript, TypeScript, Python, or Rust at the network edge. There is no server to rent, no operating system to patch, and no container to keep warm: you write a small function, run one deploy command, and your code runs on Cloudflare's global network.

This is a Cloudflare Workers tutorial for beginners in the complete sense: the mental model, the prerequisites, the scaffold, local testing, the deploy, routes and custom domains, secrets, and the free-tier boundary. By the end you will have a Worker running at a real public URL, and you will know exactly which decisions matter when you outgrow the toy version. If you already know a web framework, you can even bring it with you — the Hono beginner guide walks through the tiny framework that deploys straight to Workers with a single command.

What Is Cloudflare Workers, Exactly?

Cloudflare Workers is a serverless execution platform that runs your code on Cloudflare's edge network — thousands of machines distributed across hundreds of locations — so every request is handled by the data center nearest the user instead of traveling to one distant server. You write the code; Cloudflare runs it for you, automatically, everywhere, and you pay only for what runs, never for idle time.

An independent beginner guide puts the idea memorably: "Workers is like a barista who appears the instant someone orders, makes exactly one cup, and disappears — you only pay per cup." There is no machine to set up, no operating system to patch, and no scaling to plan. Your code wakes up only when a request comes in, runs, and goes back to sleep.

The typical first uses are small and global: APIs, webhooks, URL shorteners, auth glue, image resizing, A/B test logic, and full-stack apps built from Workers plus Cloudflare's storage pieces (KV, D1, R2). This guide keeps you on the core loop — first Worker to live URL — and points at the rest where it matters.

How Is the Edge Different From a Server?

The difference is how your code gets its own execution space. Under the hood, the Workers runtime uses the V8 engine — the same engine used by Chromium and Node.js — and V8 orchestrates isolates: lightweight contexts that give your code the variables it can access and a safe sandbox to execute within.

Instead of creating a virtual machine for each function, an isolate is created inside an existing environment, and Cloudflare says it plainly: "this model eliminates the cold starts of the virtual machine model." Any given isolate can start around a hundred times faster than a Node process on a container or virtual machine, while consuming an order of magnitude less memory at startup.

That is the practical split to remember against the container world you may know: containers give you a full runtime and long-running processes, while Workers gives you tiny, fast, event-driven functions measured in milliseconds of CPU. If containers are your home base, the Docker beginner guide covers the other side of the fence — the comparison table later in this article tells you when to pick each.

What Do You Need Before You Start?

Three things, and only three. First, Node.js and npm installed on your machine (the tooling below is all npm-based). Second, a free Cloudflare account — the Free plan is genuinely enough for this entire tutorial, and the free-tier numbers are verified against Cloudflare's current pricing page below. Third, enough JavaScript to read a short function; TypeScript works too, and Python and Rust are also supported by the platform.

The account is the only thing that takes a minute: sign up at Cloudflare, and if you want the account-and-DNS side explained in the same plain style, the Cloudflare beginner guide covers it. Nothing else needs provisioning — there is deliberately no server, no database, and no SSH key in this tutorial.

How Do You Create Your First Worker?

You scaffold with C3, Cloudflare's create tool. One command creates a ready-to-run project — no templates to hunt down, no config to write by hand:

npm create cloudflare@latest -- first-worker
cd first-worker

C3 (create-cloudflare-cli) walks you through a short set of prompts. Answer them the beginner way: pick the Hello World example, the Worker only template, and JavaScript; say yes to git, yes to the AGENTS.md file (it helps AI coding tools understand Cloudflare's APIs), and no to deploying right away — you want to look at the code first.

What lands in the folder is small and legible: wrangler.jsonc (the Wrangler config file — JSONC is the current format; the older TOML file is legacy), src/index.js (the minimal Hello World in ES-module syntax), package.json and package-lock.json. The generated handler is the entire mental model in five lines:

export default {
  async fetch(request, env, ctx) {
    return new Response('Hello World!');
  },
};

Two details the official learning path (updated August 2026) asks beginners to respect. First, the compatibility_date in the config pins the runtime's behavior to a known snapshot, so a future Cloudflare runtime change cannot silently alter how your already-deployed Worker behaves. Second, the Worker name you chose becomes part of your public URL, so if you plan to use a workers.dev subdomain the name must be 63 characters or less and cannot start or end with a dash.

How Do You Test It Locally With Wrangler?

Wrangler is Cloudflare's command-line tool for developing and deploying Workers, and the beginner move is to run everything locally first. Start the local dev server:

npx wrangler dev

Now open http://localhost:8787 in your browser: your Worker responds, and console.log output plus exceptions appear right in your terminal. Edit src/index.js, save, and the response updates — the local loop is instant and costs nothing.

One honest caveat from the official docs: by default, wrangler dev executes your Worker in a local workerd process, which is not a hardened sandbox — only run code you trust. Cloudflare also recommends calling Wrangler per project with npx wrangler … rather than installing it globally, so each project pins its own version instead of depending on whatever happens to be installed machine-wide.

How Do You Deploy It Live?

Ready to deploy first Cloudflare Worker code to the edge? Going from a file on your laptop to a public URL on Cloudflare's network takes three commands and one click of permission:

1. Log in. Run npx wrangler login. Your browser opens, you sign in to the Cloudflare dashboard, and you are asked whether Wrangler can make changes to your account — scroll down and select Allow.
2. Deploy. Run npx wrangler deploy. That single command — "deploy your Worker to Cloudflare" — publishes the code to the global network.
3. Open your URL. Your Worker is now live at <WORKER>.<SUBDOMAIN>.workers.dev, for example first-worker.yourname.workers.dev. If you have never configured a subdomain, Wrangler prompts you to set one up during the deploy.
4. Verify with a real request. Curl the URL or open it in a browser; change the response text in src/index.js, run npx wrangler deploy again, and watch the live page change. Deploys are fast — that is the whole point of the platform.
5. Preview before you ship. For bigger changes, npx wrangler deploy --dry-run validates the deploy without publishing, and npx wrangler deploy --env staging targets a named environment instead of production.

That is the complete first-Worker arc: scaffold with C3, develop with wrangler dev, authenticate with wrangler login, and publish with wrangler deploy. Everything after this — routes, secrets, storage — is production hygiene on top of that loop.

Routes or Custom Domain: Which Should You Pick?

The workers.dev URL you just got is the fast path, not the destination. Cloudflare assigns every Worker a workers.dev route automatically, but the official routing docs are blunt about its role: "It's recommended to run production Workers on a Workers route or custom domain, rather than on your workers.dev subdomain. Your workers.dev subdomain is treated as a Free website and is intended for personal or hobby projects that aren't business-critical."

There are three route types. Custom domains make the Worker the origin for a domain or subdomain in your Cloudflare zone — Cloudflare creates the DNS record and the SSL certificate automatically. Routes sit in front of an existing origin behind the Worker and need a proxied (orange-clouded) DNS record. And workers.dev is the automatic starter route for each Worker.

The operator rule that matters most is route order: when more than one route pattern could match a request, the most specific route pattern wins — www.example.com/* beats *.example.com/*, and example.com/hello/* beats example.com/*. Declaration order does not decide; specificity does. Deploy a custom domain with the official flag, not the cheat-sheet version that floats around: npx wrangler deploy --domain example.com. And when you go custom, you can switch the starter route off with workers_dev = false in the config — adding any routes block auto-infers that on the next deploy anyway.

Where Do Secrets Go?

Secrets — API keys, auth tokens, connection strings — are a type of binding: encrypted text values attached to your Worker. The rule from Cloudflare's best-practices page is a one-liner: store secrets with wrangler secret, not in source. Never bake them into src/index.js or commit them to git.

The current flow is simple. Set one with:

npx wrangler secret put API_KEY

Wrangler prompts for the value interactively (use an env-var pipe in CI), and — this surprises beginners — wrangler secret put creates a new version of the Worker and deploys it immediately. Inside your code the secret arrives on the env parameter you already saw in the handler, e.g. env.API_KEY, or via import { env } from "cloudflare:workers". Once defined, the value is not visible in Wrangler or the dashboard again. For local development, put dev secrets in .dev.vars next to the config; for pipelines, npx wrangler deploy --secrets-file .env.production uploads a batch (up to 100 secrets per request).

What Does the Cloudflare Workers Free Tier Actually Give You?

The free tier is the reason this tutorial needs no credit card, and Cloudflare's pricing page (updated October 2026) publishes the numbers plainly. The headline figure for the whole Cloudflare Workers free tier is 100,000 requests per day with 10 milliseconds of CPU time per invocation — and there are no charges for duration, data transfer, or bandwidth:

When you outgrow free, the Paid plan starts at $5/month with 10 million requests and 30 million CPU-milliseconds included per month, and the maximum CPU per invocation rises to 5 minutes (30 seconds by default). The honest beginner reading of this table: requests are generous, CPU time is the constraint — design handlers that do their work fast and hand long jobs to Queues or a scheduled Worker.

Cloudflare Workers vs a VPS: When Is Each Right?

The Cloudflare Workers vs VPS question is the one every beginner actually has, because Workers and a virtual private server solve overlapping problems with opposite philosophies. A Worker is an event-driven function on someone else's global network; a VPS (what is VPS hosting) is your own server — full OS, always on, billed by the month whether or not anyone visits.

The one-sentence version: pick Workers when your work is request-shaped and should be fast everywhere; pick a VPS when your work is machine-shaped and needs to own the box. Many real architectures use both — a Worker at the edge in front of a VPS origin is a classic pairing.

5 Beginner Mistakes That Waste Your First Week

These are the traps the official docs warn about indirectly and the independent guides warn about loudly. All five are avoidable in the first hour:

Sources

Every figure, command, and quoted claim in this guide was verified against these pages on November 3, 2026:

• Cloudflare Learning Path, "First Worker" (developers.cloudflare.com/learning-paths/workers/get-started/first-worker/) — the C3 scaffold flow, prompts, and generated files; updated August 25, 2026.
• Cloudflare Workers Pricing (developers.cloudflare.com/workers/platform/pricing/) — Free and Paid plan limits; updated October 2, 2026.
• Cloudflare Workers Routing docs (developers.cloudflare.com/workers/configuration/routing/) — route types, route-order rule, and the workers.dev production guidance.
• Cloudflare Secrets docs (developers.cloudflare.com/workers/configuration/secrets/) — the wrangler secret flow and best practices; updated October 15, 2026.
• Cloudflare "How Workers Works" (developers.cloudflare.com/workers/reference/how-workers-works/) — V8 isolates, cold starts, and the fetch handler; updated September 18, 2026.
• Cloudflare Wrangler Commands (developers.cloudflare.com/workers/wrangler/commands/workers/) — wrangler dev, deploy, and login behavior.
• Cloudflare Get Started Guide (developers.cloudflare.com/workers/get-started/guide/) — the CLI onboarding flow.
• Peteraim, "Cloudflare for Beginners" (cloudflare-intro.peteraim.com/en/workers.html) — the barista analogy and plain-English glossary.
• OpenReplay, "A Beginner's Guide to Cloudflare Workers" (blog.openreplay.com/beginners-guide-cloudflare-workers/) — D1, Hyperdrive, and the Node.js compatibility layer.
• C# Corner, "Cloudflare Workers Tutorial: Build and Deploy Your First Edge Application" (c-sharpcorner.com) — project structure and the request-flow mental model.

Frequently Asked Questions

Is Cloudflare Workers really free?

Yes, for real workloads up to the published limits: 100,000 requests per day and 10 milliseconds of CPU per invocation, plus free allowances for KV, D1, R2, and Queues, with no charge for data transfer or bandwidth. Exceeding a daily limit fails that type of operation rather than silently billing you, so the free tier is a safe place to learn.

What languages can Workers run?

JavaScript and TypeScript are first-class, and Python and Rust are also supported on the platform. The handler you write is the same shape in every language: an exported function that receives the request and returns a response.

Do Workers have cold starts?

Not in the container sense. Because isolates start inside an already-running environment rather than booting a virtual machine, Cloudflare states the model "eliminates the cold starts of the virtual machine model" — an isolate can start around a hundred times faster than a Node process on a container or VM.

Can I use my own domain with a Worker?

Yes. Attach a custom domain and the Worker becomes the origin for it, with Cloudflare handling DNS and SSL automatically — deploy with npx wrangler deploy --domain example.com. Alternatively, attach routes so the Worker runs in front of an existing origin. Either way, keep production off the workers.dev starter URL.

When should I pick a VPS instead of Workers?

Pick a VPS when your work is machine-shaped: long-running processes, background daemons, full OS control, root access, or software that needs installing. Pick Workers when your work is request-shaped and should be fast everywhere. The comparison table above and the what-is-VPS-hosting guide walk through the tradeoffs in full.