Introduction to Wrangler CLI: Setup and Project Initialization

Previously in this course, we explored deploying a static frontend. Now that your site is live on the edge, it’s time to move from static assets to dynamic serverless code using Cloudflare Workers. To do this, we need the right toolset.

Wrangler is the official command-line interface (CLI) for Cloudflare Workers. Think of it as your primary workstation for everything related to serverless development—from local testing and secret management to final production deployments. Mastering the CLI is as critical to your workflow as understanding version control with Git or managing your local development environment.

Why You Need Wrangler for Workers

While you can edit code in the Cloudflare Dashboard, that approach doesn't scale. Wrangler provides a professional development loop:

1. Local Development: Run your code on your machine before pushing to the edge.
2. Configuration: Manage your wrangler.toml file, which defines your environment variables, storage bindings, and deployment routes.
3. Deployment: Automate the upload of your code and assets to the global Cloudflare network.

Installing the Wrangler CLI

Wrangler is distributed as an npm package. Ensure you have Node.js installed (version 18.0.0 or higher is recommended).

Open your terminal and run the following command to install Wrangler globally:

Bash
npm install -g wrangler

Once the installation finishes, verify it by checking the version:

Bash
wrangler --version

If you see a version number, you're ready to proceed. If you prefer not to install it globally, you can use npx wrangler instead of wrangler for every command throughout this course.

Authenticating with Cloudflare

Before Wrangler can interact with your account, it needs permission. Running the authentication command will open your browser to log in to the Cloudflare dashboard.

Execute this in your terminal:

Bash
wrangler login

After you click "Authorize" in your browser, Wrangler will securely store an API token on your machine. You won't need to log in again unless you clear your local configuration or revoke the token in your Cloudflare dashboard.

Initializing Your Project

We are going to build a full-stack application throughout this course. Let’s create the directory for our new project.

Navigate to your workspace folder and run:

Bash
wrangler init my-edge-app

Wrangler will prompt you with a few setup questions:

• Would you like to use TypeScript? (Recommended: Yes)
• Would you like to create a wrangler.toml file? (Yes)
• Would you like to deploy via Git? (Optional for now, select No)

This command creates a folder named my-edge-app containing:

• src/index.ts: The entry point for your Worker code.
• wrangler.toml: The configuration file where we will eventually define our D1 and R2 bindings.
• package.json: Your project's dependency manifest.

Hands-on Exercise

1. Navigate into your new directory: cd my-edge-app.
2. Open the wrangler.toml file in your code editor.
3. Observe the main field; this points to your src/index.ts.
4. Run npx wrangler dev to start the local development server.
5. Visit the URL provided in your terminal (usually http://localhost:8787) to see your "Hello World" Worker in action.

Common Pitfalls

• Node.js Version: If you encounter errors during installation, check your Node version (node -v). Older versions often lack support for modern features used by the CLI.
• Authentication Loops: If your browser doesn't open automatically during wrangler login, copy the URL provided in the terminal and paste it into your browser manually.
• Global vs. Local: If you get a "command not found" error, try prepending npx (e.g., npx wrangler dev). This ensures you are using the version installed locally in your node_modules.

FAQ

Do I need a paid plan to use Wrangler? No, Wrangler is free to use. You can develop and deploy Workers on the Cloudflare Free plan.

Can I use Wrangler for multiple projects? Yes, each project is defined by its own wrangler.toml file. You can manage as many projects as you like on your machine.

Is there a GUI for this? Cloudflare provides a dashboard for basic editing, but for real, production-grade applications, the CLI is the industry standard.

Recap

In this lesson, we installed the Wrangler CLI, authenticated with our Cloudflare account, and initialized our project directory. You now have a local workspace ready for serverless development.

Up next: We will write our first Worker script and learn how to handle HTTP requests.