Skip to content
Adventive Adventive Engineering

Workers Project Quick Start

This is the fast path from nothing to a deployed Adventive Worker. It uses the adventive-worker-template scaffold, which ships every platform default already wired — environments, OpenTelemetry, per-role Hyperdrive, Secrets Store, an optional auth binding, structured logging, tests, and CI. Follow it top to bottom and you will have a working dev Worker on your own hostname.

New to the standards behind each step? Each section links to the authoritative reference. Read Workers and Hyperdrive at some point, but you do not need them memorized to start.

Prerequisites

Section titled “Prerequisites”
  • Node 20+ and npm.
  • wrangler (installed per-project via the template’s dependencies — no global install needed).
  • gh (GitHub CLI), authenticated to the adventive org.
  • Cloudflare access to the Adventive Tech, Inc. account (46a873457665355ba02a85e61d7200a7).
  • Your sandbox env sourced (. ~/Documents/Claude/.cowork-env) so wrangler picks up credentials.

1. Clone the template into a new repo

Section titled “1. Clone the template into a new repo”

The template is a scaffold, not a fork parent — copy it, then start fresh history.

cd ~/Repositories/GitHub/Adventive
cp -R adventive-worker-template adventive-<name>-worker
cd adventive-<name>-worker
rm -rf .git && git init -b main
npm install

If you don’t have the template locally yet:

gh repo clone Adventive/adventive-worker-template adventive-<name>-worker
cd adventive-<name>-worker && rm -rf .git && git init -b main && npm install

2. Fill in the placeholders

Section titled “2. Fill in the placeholders”

Every project-specific value is marked REPLACE_ME. Find them all:

grep -rn "REPLACE_ME" .
TokenWhat to put
REPLACE_ME_NAMEyour Worker’s short kebab-case name (billing-sync, report-api, …)
REPLACE_ME_HOSTthe route hostname, or delete the routes lines for an internal-only Worker
REPLACE_ME_DBthe database this Worker reads (console, billing, aggregate, …)
REPLACE_ME_HD_*Hyperdrive config IDs (see step 4)

Naming follows Workers SOP §01: adv-{ui|svc}-{name}-{env}. The base name goes on the wrangler.toml top level; per-env names live in each [env.<env>] block.

Then delete the bindings you don’t use from both wrangler.toml and src/env.ts (Hyperdrive RW, AUTH, KV, Durable Objects, assets). Keep the two in lockstep — src/env.ts is the type view of wrangler.toml.

3. Environments

Section titled “3. Environments”

The template ships four:

Envwrangler targetPurpose
devtop-level (--env dev)shared dev on *.adventive.dev
staging--env staging*.adventivestg.com
production--env production*.adventive.com
personal--env personalyour own *.workers.dev scratch Worker (OTel off by default)

Staging and production Hyperdrive IDs and routes are placeholders until you promote past dev — fill them when you get there.

4. Hyperdrive (database access)

Section titled “4. Hyperdrive (database access)”

Databases are private in AWS and reached over the Cloudflare Tunnel through per-role Hyperdrive connectors. The naming is fully derivable — see the Connection & Credential Naming Standard:

  • Config: adv-hd-<db>-<role>-<env> (e.g. adv-hd-console-ro-dev)
  • MySQL user: hd_<db>_<role> (e.g. hd_console_ro)
  • Binding: DB_<DB>_<MODE> (e.g. DB_CONSOLE_RO)

Bind only the roles you use. A read-only Worker binds *_RO and never sees a write credential (least privilege — this is the whole point of the split). List the config IDs and paste them into wrangler.toml:

wrangler hyperdrive list

src/lib/db.ts already sets the two runtime flags the CF/mysql2 path requires (disableEval: true, and query() instead of execute()). Don’t remove them.

5. OpenTelemetry

Section titled “5. OpenTelemetry”

src/worker.ts wraps the app with OTel → New Relic. It’s controlled entirely by vars:

  • OTEL_ENABLED — "true" instruments and exports; "false" makes the wrapper a no-op (no Secrets Store read, no exporter). personal defaults to "false".
  • OTEL_SERVICE_NAME / service.namespace in OTEL_RESOURCE_ATTRIBUTES — how this Worker shows up in New Relic. Set the namespace to adventive.<name>.

The New Relic ingest key resolves from Cloudflare Secrets Store at runtime; you never paste it. Full detail: Workers → Observability / OpenTelemetry.

6. Secrets

Section titled “6. Secrets”

Runtime secrets resolve from the account Secrets Store via await env.SECRET.get() — never wrangler secret put, never a committed .dev.vars in a deployed env (Security & Secrets Policy). Copy .dev.vars.example to .dev.vars (gitignored) only for local values.

7. Run, check, deploy

Section titled “7. Run, check, deploy”
npm run dev          # wrangler dev --env dev
npm run typecheck
npm run test
npm run lint

Deploys run from your sandbox, never from CI (SOP §3.2). CI on a PR runs lint/typecheck/test and a dry-run only.

npm run deploy:dev           # wrangler deploy --env dev
npm run tail:dev             # live logs

Confirm the deploy with the built-in health route:

curl https://<host>.adventive.dev/__health
# {"status":"ok","commit_sha":"…","environment":"dev"}

8. Create the GitHub repo and push

Section titled “8. Create the GitHub repo and push”
git add -A
git commit -m "Initial commit: adv-svc-<name> Worker"
gh repo create Adventive/adventive-<name>-worker --private --source=. --remote=origin --push

Opening a PR against main triggers the CI gate. Deploy from your sandbox after it’s green.

Where to go next

Section titled “Where to go next”