# Wrangler Setup Guide

Step-by-step guide for creating a minimal wrangler.toml for Cloudflare Workers Static Assets.

## Prerequisites

- Node.js installed (for `npx wrangler`)
- Cloudflare account with API token (see [1Password setup](./onep-credential-setup.md))

## Minimal wrangler.toml

```toml
# Cloudflare Workers Static Assets
# Deploy: mise run publish:{task} (or bash scripts/publish_{project}.sh)
name = "{worker-name}"
compatibility_date = "{YYYY-MM-DD}"

[assets]
directory = "."
```

**Three fields. That is all.** No `main`, no `route`, no `zone_id`.

## Field Reference

| Field                | Required | Value                      | Notes                                              |
| -------------------- | -------- | -------------------------- | -------------------------------------------------- |
| `name`               | YES      | Worker name (kebab-case)   | Becomes `{name}.{slug}.workers.dev`                |
| `compatibility_date` | YES      | ISO date (YYYY-MM-DD)      | Use today's date; controls API behavior versioning |
| `[assets] directory` | YES      | `"."`                      | Relative to wrangler.toml location                 |
| `main`               | NO       | Omit entirely              | Not needed for static-only                         |
| `route`              | NO       | Omit entirely              | workers.dev route is automatic                     |
| `zone_id`            | NO       | Omit entirely              | Not needed without custom domain                   |
| `account_id`         | NO       | Omit (use env var instead) | Set via `CLOUDFLARE_ACCOUNT_ID` env var            |

## Worker Name Conventions

Choose a descriptive, unique name:

- `rangebar-findings` — research project findings
- `trading-dashboards` — dashboard collection
- `{project}-static` — generic pattern

The name must be globally unique within your Cloudflare account.

## Directory Structure

Place wrangler.toml at the root of the directory to serve:

```
results/published/                # <-- wrangler.toml goes here
├── wrangler.toml
├── index.html                    # Root page (auto-generated by deploy script)
└── gen800/                       # Subdirectory hierarchy
    └── XRPUSDT_750/
        └── equity_plot.html      # Served at /gen800/XRPUSDT_750/equity_plot.html
```

All files under the `directory` path are deployed. Workers serves them by exact path match.

## Compatibility Date

Set to the date you first create the worker. You do not need to update it unless you want to opt into new runtime behavior.

## Verification

Validate config without deploying:

```bash
cd results/published/
npx wrangler deploy --dry-run 2>&1
```

## Custom Domains (Optional, Advanced)

To use a custom domain instead of workers.dev:

1. Add domain to Cloudflare (requires DNS management)
2. Add `routes` to wrangler.toml:

```toml
routes = [
  { pattern = "static.example.com/*", zone_name = "example.com" }
]
```

This is outside the scope of the basic static hosting workflow.
