say-it/README.md

# Something to Say

URL-based poster maker on Cloudflare Workers. paste text into the URL and get a styled image back.

## Prerequisites

- Node.js 18+
- A Cloudflare account with Workers enabled
- (Optional) An Upstash Redis account for PNG caching

## Setup

### 1. Install dependencies

```sh
npm install
```

### 2. Login to Wrangler (Cloudflare CLI)

```sh
npx wrangler login
```

A browser window opens — authorise the CLI to access your Cloudflare account.

### 3. Create the D1 database (request tracking)

```sh
npx wrangler d1 create image_cache_db
```

Copy the returned `database_id` into `wrangler.toml` under `[[d1_databases]]`.

Then run the migration:

```sh
# local dev
npx wrangler d1 execute image_cache_db --local --file=./schema.sql

# production (after first deploy)
npx wrangler d1 execute image_cache_db --remote --file=./schema.sql
```

### 4. Set up Upstash Redis (optional, for PNG caching)

PNG generation is slow without caching. SVG is instant. Redis caches generated PNGs so repeat requests are fast.

1. Go to https://upstash.com and sign up
2. Create a **Redis** database (free tier is enough)
3. Copy the **REST URL** and **REST Token** from the dashboard

**For local dev:** Create `.dev.vars` in the project root:

```
UPSTASH_REDIS_REST_URL=https://your-upstash-url.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-token
```

**For production:**

```sh
npx wrangler secret put UPSTASH_REDIS_REST_URL
# paste the URL, press Enter, Ctrl+D

npx wrangler secret put UPSTASH_REDIS_REST_TOKEN
# paste the token, press Enter, Ctrl+D
```

### 5. Configure a custom domain

Before you can route a worker to your own domain, the domain must exist in your Cloudflare account as a **zone**.

**If your domain isn't in Cloudflare yet:**

1. Go to the Cloudflare dashboard → **Add a Site**
2. Enter your domain (e.g. `mydomain.com`), pick the free plan
3. Cloudflare will show two nameserver addresses (e.g. `ns1.cloudflare.com`, `ns2.cloudflare.com`)
4. At your domain registrar, update the nameservers to those Cloudflare-provided ones
5. Wait for propagation (minutes to hours — Cloudflare checks automatically)
6. Your domain now appears under **Websites** in the dashboard

Once the domain is in Cloudflare, you have two options:

> **Note:** Worker custom domains are managed under **Workers & Pages** in the Cloudflare dashboard (not the DNS section). The dashboard shows each custom domain's status and lets you remove or re-trigger provisioning.

#### Option A: automatic via `custom_domain` (recommended)

Add to `wrangler.toml`:

```toml
routes = [
  { pattern = "yourdomain.com", custom_domain = true }
]
```

On deploy (`npx wrangler deploy`), Cloudflare auto-provisions the DNS record and SSL certificate. No manual DNS changes needed.

Also update `PUBLIC_BASE_URL` so OG image URLs are correct:

```toml
[vars]
PUBLIC_BASE_URL = "https://yourdomain.com"
```

#### Option B: manual CNAME record

If `custom_domain` doesn't work (e.g. the zone isn't fully active yet), create the record manually:

1. Cloudflare dashboard → your domain → **DNS**
2. **Add Record**:
   - Type: `CNAME`
   - Name: the subdomain, e.g. `say` (for `say.mydomain.com`)
   - Target: your worker's `*.workers.dev` URL (shown after `wrangler deploy`, e.g. `my-worker.jeancnicolas.workers.dev`)
   - Proxy: Proxied (orange cloud)
3. Remove the `routes` block from `wrangler.toml` (the CNAME handles routing instead) or keep it — they can coexist.

#### Verify

After deploying with either option, visit your domain. If it doesn't resolve, check:

- **Is the domain listed under Websites in your Cloudflare dashboard?** If not, add it first (steps above).
- **Did you redeploy after adding the route?** Run `npx wrangler deploy` again.
- **Check route status:** `npx wrangler triggers` shows the current routes for your worker.
- **DNS propagation:** `dig say.mydomain.com` or use an online DNS checker to see if the record resolves.

## Local dev

```sh
npm run dev
```

Opens at `http://localhost:8787`.

## Deploy

```sh
npx wrangler deploy
```

### First deploy checklist

After the first deploy:

1. **D1 migration** (if not done yet):
   ```sh
   npx wrangler d1 execute image_cache_db --remote --file=./schema.sql
   ```
2. **Redeploy** to pick up any config changes:
   ```sh
   npx wrangler deploy
   ```

## How it works

- `/` — interactive editor (drag sliders, pick themes, preview live)
- `/say/hello/world?theme=neon-noir` — styled poster as SVG (instant)
- `/say/hello/world?theme=neon-noir&png` — styled poster as PNG (slower, cached)
- `?svg` / `?png` — explicitly request format
- `?preset=x` — platform presets (twitter, linkedin, instagram, etc.)
- `?vw=N` — custom viewport width (px)
- `?scale` — fluid mode (lines fill the container width)
- `?ir=0.8` — inner content width ratio (0.3–1.0, default 1.0)
- Inline markers: `**bold**`, `*italic*`, `==highlight==`, `~underline~`, `{accent:text}`, `{color:text}`

## Updating secrets

To update an existing secret:

```sh
npx wrangler secret put UPSTASH_REDIS_REST_URL
```

Then redeploy. No code changes needed.

## Viewing logs

```sh
npx wrangler tail
```

## Cache headers

PNG responses include `X-Cache: HIT` or `X-Cache: MISS` so you can verify Redis caching in the Network tab.