Skip to content

LOCAL_DEVELOPMENT.md

Latest commit

 

History

History
120 lines (76 loc) · 5.79 KB

LOCAL_DEVELOPMENT.md

File metadata and controls

120 lines (76 loc) · 5.79 KB

Local development (monorepo)

How to run and test the template app (apps/template) and the bodegacat integration on your machine. Admin routes work without Cloudflare Access in dev.

Use pnpm from the repository root. Stripe keys belong in apps/template/.env. Integration source is packages/bodegacat.

Deploying to Cloudflare (KV, Pages env vars, wrangler, Access): see examples/deploy/cloudflare-pages/README.md. This doc stays focused on local astro dev and monorepo workflows.

Quick start

  1. Install

    pnpm install

  2. Environment

    cp env.example apps/template/.env

    Edit apps/template/.env with your Stripe test keys and, for admin dev bypass:

    STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NODE_ENV=development

  3. Run

    pnpm dev

    Open http://localhost:4321.

Admin in development

In dev (NODE_ENV=development or import.meta.env.DEV), middleware skips Cloudflare Access, sets a mock user (dev@localhost), and shows a Development mode indicator on screen.

In production, /admin/* expects Cloudflare Access (see the deploy guide, section 6).

Admin while testing pnpm preview / wrangler dev (built app)

astro dev is not the same as running the built Worker. To use /admin on local wrangler without Cloudflare Access:

  1. Add to apps/template/.dev.vars (copy from apps/template/dev.vars.example):

    BODEGACAT_ADMIN_LOCAL_BYPASS=true

    Wrangler injects this at runtime (keep Stripe keys here too for preview).

  2. Run pnpm --filter @bodegacat/template preview (or pnpm preview from repo root).

  3. Open http://localhost:8787/admin (or the URL wrangler prints). The bypass applies only when the request host is loopback (localhost, 127.0.0.1, etc.) — not on a real deployed hostname.

  4. Never set BODEGACAT_ADMIN_LOCAL_BYPASS in production Cloudflare env.

Useful routes:

Path Purpose
/admin Dashboard
/admin/products Product list
/admin/products/new Create product
/api/admin/products List/create (API)
/api/stripe-webhook Webhook endpoint

Storefront preview (unpublished products)

Products can be active in Stripe but not published to the public catalog (metadata.bodegacat_published=false). The public site (/, /shop, /shop/[slug]) is prerendered (astro build) and shows only published items from Stripe at build time, plus getSiteConfig() (defaults + optional SITE_* env) — not KV. Draft preview is SSR under /preview, /preview/shop, /preview/shop/[slug] — same staff auth as /admin (dev bypass locally; Cloudflare Access in production).

Environment How to open preview
Local dev Visit /preview or /preview/shop (middleware uses the same dev user as admin).
Production Cloudflare Access must allow /preview* (mirror your /admin policy).

The admin nav links to /preview when you have draft products. Uncheck Published on storefront until you are ready; then redeploy (or use the webhook build hook below) so the static catalog updates.

Full static rebuilds (deploy hook)

Changing products or prices in Stripe does not update prerendered HTML until the next astro build.

  • Recommended (batch edits): leave STRIPE_WEBHOOK_AUTO_DEPLOY unset or false. Stripe webhooks still verify and log, but they do not trigger a deploy on every product save. When staff are happy, use Admin → Deploy live site (calls BUILD_HOOK_URL) for one production build — same as a git push to main.
  • Optional: set STRIPE_WEBHOOK_AUTO_DEPLOY=true if you want product.* / price.* Stripe events to call BUILD_HOOK_URL automatically (can mean many deploys).

That rebuild bakes catalog from Stripe at build time and SITE_* from the build environment. KV (admin UI) does not update prerendered / or /shop HTML; align with CLAUDE.md / .cursor/rules/bodegacat-storefront-architecture.mdc.

Set BUILD_HOOK_URL in production to your Pages deploy hook URL (see the Cloudflare deploy guide).

Stripe test data

Use the Stripe Dashboard (test mode) for products and webhooks. Required product metadata (bodegacat_active, slug, prices, etc.) is documented in VARIATION_SYSTEM.md and summarized on the repository README.

For card numbers and test mode behavior, see Stripe testing.

Troubleshooting

Issue What to check
Admin not loading NODE_ENV=development in .env, pnpm dev from repo root, browser console
Stripe / empty shop Keys match test mode, products exist with correct metadata (see VARIATION_SYSTEM)
Draft not on /shop Expected until published or use /preview/shop; public /shop is static until rebuild
Type / lint errors pnpm run typecheck, pnpm run lint from repo root

After local testing

Staging/production, Cloudflare Access, and Stripe live mode are covered in the Cloudflare deploy guide.

Related links