Setting Up Your Workspace for AI Development

Welcome to the workshop. Before we can start architecting universes, we need to get our tools in order. A clean, consistent, and powerful local development environment is not just a convenience; it’s the foundation for everything we’ll build. The goal is to create a setup that lets you iterate quickly, test reliably, and deploy with confidence.

This chapter is a practical, hands-on guide to configuring your local machine for building AI-driven Cloudflare Workers. We'll install the necessary tools and create a starter template that will serve as the launchpad for all our future projects.

The Foundational Layer: Node.js and Git

Our entire development workflow relies on the Node.js ecosystem and the Git version control system.

• Node.js: All of our dependencies, build tools, and local development servers run on Node.js. We recommend using the latest Long-Term Support (LTS) version. If you manage multiple Node.js versions, a tool like nvm (Node Version Manager) is indispensable.
• Git: Every project should be a Git repository from the very beginning. It's your safety net, your collaboration tool, and your history book.

Wrangler: Your Command-Line Control Panel

If there is one tool you will get to know intimately, it’s wrangler. This is Cloudflare’s official command-line interface (CLI) for managing every aspect of your Workers. You'll use it to create, test, and deploy your agents.

You can install it globally in your project using npm:

```bash

npm install --save-dev wrangler

```

Once installed, the first thing you need to do is connect wrangler to your Cloudflare account.

```bash

npx wrangler login

```

This will open a browser window, ask you to log in to Cloudflare, and grant wrangler the necessary permissions to act on your behalf.

The "Hello Agent" Template

The best way to understand the setup is to build it. We're going to create a simple "Hello Agent" worker. Here are the four key configuration files that define its universe.

1. package.json: The Project's Recipe

This file is the heart of any Node.js project. It lists your dependencies and, most importantly, defines the scripts you'll use for common tasks.

Create a file named package.json:

```json

{

"name": "hello-agent",

"version": "0.1.0",

"private": true,

"type": "module",

"scripts": {

"dev": "wrangler dev src/index.ts",

"deploy": "wrangler deploy --minify src/index.ts",

"test": "vitest run",

"typecheck": "tsc --noEmit"

},

"devDependencies": {

"@cloudflare/workers-types": "^4.20260725.0",

"typescript": "^5.5.3",

"vitest": "^1.6.0",

"wrangler": "^3.64.0"

},

"dependencies": {

"hono": "^4.5.1"

}

}

```

Let's break down the scripts:

• "dev": Starts a local development server that automatically reloads when you change your code.
• "deploy": Builds and publishes your worker to the Cloudflare global network.
• "test": Runs your test suite using vitest (we'll cover this in a later chapter).
• "typecheck": Checks your code for any TypeScript errors without compiling it.

2. tsconfig.json: The TypeScript Guardian

This file configures the TypeScript compiler, ensuring our code is strict, modern, and compatible with the Cloudflare Workers runtime.

Create a file named tsconfig.json:

```json

{

"compilerOptions": {

"target": "ESNext",

"module": "ESNext",

"moduleResolution": "bundler",

"lib": ["ESNext", "DOM"],

"jsx": "react-jsx",

"strict": true,

"skipLibCheck": true,

"noEmit": true,

"allowJs": true,

"paths": {

"~/": ["./src/"]

},

"types": ["@cloudflare/workers-types"]

},

"include": ["src", "tests"]

}

```

The most important lines are:

• "strict": true: This enables all of TypeScript's strict type-checking options. It might feel painful at first, but it will save you from countless bugs down the road.
• "moduleResolution": "bundler": This is the modern standard for how Node.js and bundlers resolve modules.
• "types": ["@cloudflare/workers-types"]: This tells TypeScript to include the official type definitions for the Workers runtime, giving you auto-completion and type safety for things like Request, Response, and your environment bindings.

3. wrangler.toml: The Worker's Soul

This file is specific to Cloudflare and tells wrangler everything it needs to know about your worker: its name, its entry point, its compatibility settings, and, crucially, how it connects to other Cloudflare resources.

Create a file named wrangler.toml:

```toml

name = "hello-agent"

main = "src/index.ts"

compatibility_date = "2024-07-25"

compatibility_flags = ["nodejs_compat"]

Example of a D1 Database binding

[[d1_databases]]

binding = "DB"

database_name = "my-database"

database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Example of an R2 Bucket binding

[[r2_buckets]]

binding = "BUCKET"

bucket_name = "my-bucket"

For local development, create a .dev.vars file and add secrets there

Example: MY_SECRET = "super_secret_value"

[vars]

AI_MODEL = "@cf/meta/llama-3-8b-instruct"

```

• main: Points to the entry file of your agent's code.
• compatibility_date: Ensures your worker runs on a specific, stable version of the Workers runtime.
• [vars]: This is where you can define environment variables. For secrets, you should create a .dev.vars file (which is ignored by Git) to store them locally, and use wrangler secret put to set them in production.
• Bindings (commented out): This is a core concept. A binding makes another Cloudflare resource, like a D1 database or an R2 bucket, available as a global variable inside your worker's code. We will use bindings extensively in later chapters.

4. src/index.ts: The Agent's First Words

Finally, let's create the actual code. Create a src directory, and inside it, a file named index.ts.

```typescript

// src/index.ts

import { Hono } from 'hono';

// The 'Bindings' type provides type safety for our environment variables

// and bindings configured in wrangler.toml.

export type Bindings = {

AI: any;

AI_MODEL: string;

};

const app = new Hono<{ Bindings: Bindings }>();

app.get('/', async (c) => {

const ai = c.env.AI;

const model = c.env.AI_MODEL;

const messages = [

{ role: 'system', content: 'You are a friendly assistant.' },

{ role: 'user', content: 'Say "Hello, Agent!"' },

];

const response = await ai.run(model, { messages });

return c.json(response);

});

export default app;

```

This simple agent uses the lightweight hono router and makes a call to Cloudflare's built-in AI Gateway. It's the perfect starting point.

Liftoff!

Your workspace is now ready. Install the dependencies:

```bash

npm install

```

And run the development server:

```bash

npm run dev

```

You can now open your browser to http://localhost:8787 and see your agent's first words. You have a solid, repeatable foundation. In the next chapter, we'll dive deeper into the essential tools and libraries you'll use every day.