### Dashcommerce Starter Development Loop

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/RESUME.md

Commands for setting up the starter project, including installation, seeding, running the development server, and configuring Stripe webhook forwarding.

```sh
cd packages/starter
bun install
bun emdash seed
bun dev                 # Astro at :4321
stripe listen --forward-to localhost:4321/_emdash/api/plugins/dashcommerce/checkout/webhook
```

--------------------------------

### Per-Package Development Loop

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/README.md

Commands to start the development server for specific packages within the Dashcommerce project.

```sh
cd packages/core && bun run dev    # tsdown --watch
cd packages/starter && bun run dev # Astro on :4321
```

--------------------------------

### Add Dashcommerce Core Package

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/README.md

Install the Dashcommerce core package using Bun.

```sh
bun add @dashcommerce/core
```

--------------------------------

### Clone and Run Dashcommerce Project

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/starter/README.md

Alternatively, clone the starter repository directly and follow these steps to install dependencies, bootstrap the project, and run the development server.

```sh
git clone https://github.com/emdashCommerce/starter
cd starter && bun install && bun run bootstrap && bun run dev
```

--------------------------------

### Initialize EmDash and Seed Data

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/README.md

Initialize EmDash, merge seed data, apply it, and start the development server.

```sh
bun emdash init
bunx dashcommerce-merge-seed
bun emdash seed --on-conflict=update
bun dev
```

--------------------------------

### Create Dashcommerce Project

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/starter/README.md

Use this command to create a new Dashcommerce project with the latest starter template. It prompts for project details and installs dependencies.

```sh
npm create @dashcommerce@latest
```

--------------------------------

### Initialize and Run Development Server

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/starter/README.md

After creating the project, navigate to the project directory and run these commands to initialize EmDash, seed the database, and start the Astro development server.

```sh
cd <your-project>
bun run bootstrap
bun run dev
```

--------------------------------

### Build and Run DashCommerce with Docker

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/starter/README.md

Commands to build the DashCommerce Docker image and run it as a container. This example shows how to map ports, set environment variables, and mount volumes for data persistence.

```sh
docker build -t ghcr.io/you/dashcommerce .
docker run -p 4321:4321 \
  -e SITE_URL=https://your-domain \
  -e DATABASE_URL=postgres://…   # optional; defaults to SQLite in /data
  -v dashcommerce_data:/data \
  -v dashcommerce_uploads:/app/packages/starter/uploads \
  ghcr.io/you/dashcommerce
```

--------------------------------

### Dashcommerce Core Development Loop

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/RESUME.md

Commands to navigate to the dashcommerce directory, install dependencies, and run type checking, build, and test commands.

```sh
cd /Users/timuzua/Dev/dashcommerce
bun install
bun run typecheck       # tsc --noEmit across workspaces
bun run build           # tsdown for core
bun test                # phase 18+ only
```

--------------------------------

### Run Docker Compose for Local Development

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/starter/README.md

Commands to start the DashCommerce application locally using Docker Compose. This includes bringing up the services and executing the bootstrap command to set up the database.

```sh
docker compose up
docker compose exec app bun run bootstrap
```

--------------------------------

### Development Commands

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/core/README.md

Run these commands to manage the development environment, including installing dependencies, checking types, building the project, watching for changes, and running tests.

```sh
bun install
bun run typecheck
bun run build          # tsdown bundles index + sandbox-entry + admin/entry
bun run dev            # tsdown --watch
bun test               # 66 tests across money / cart / coupons / webhook / tokens / split
```

--------------------------------

### Dashcommerce Infrastructure Files

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/RESUME.md

List of essential infrastructure configuration files for the monorepo. These files manage project setup, dependencies, and build processes.

```tree
- `package.json` (monorepo root + workspaces), `tsconfig.base.json`, `biome.json`, `.gitignore`, `LICENSE` (MIT), `README.md`, `CHANGELOG.md`
- `.github/workflows/ci.yml` — typecheck + build + test
- `packages/core/tsdown.config.ts` — ESM build with `.d.ts`, neutral platform
```

--------------------------------

### Handle Admin Settings Page Crash

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/CHANGELOG.md

Safeguard `saved._secrets` with optional chaining to prevent crashes on fresh installs before plugin lifecycle populates secret placeholders. This addresses a 'Cannot read properties of undefined' error.

```javascript
saved._secrets?.stripeSecretKey
```

--------------------------------

### Development Commands

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/README.md

Essential commands for setting up and running Dashcommerce during development.

```sh
bun install
bun run typecheck
bun run build
bun test          # 66 tests across money / cart / coupons / webhook / tokens / split
```

--------------------------------

### Merge Seed Data and Apply

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/README.md

Merge product collections and taxonomies into your seed file and apply them using the EmDash CLI.

```sh
bunx dashcommerce-merge-seed
bun emdash seed --on-conflict=update
```

--------------------------------

### Dashcommerce Core Specific Development Loop

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/RESUME.md

Commands to navigate to the 'packages/core' directory and run type checking, build, and development watch commands.

```sh
cd packages/core
bun run typecheck
bun run build
bun run dev             # tsdown --watch
```

--------------------------------

### Create a New DashCommerce Project

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/create/README.md

Use npm create to scaffold a new DashCommerce project. You can specify a project name or use the default. The --template flag allows you to choose a specific template.

```sh
npm create @dashcommerce@latest
# or
npm create @dashcommerce@latest my-shop
# or
npm create @dashcommerce@latest my-shop -- --template starter
```

--------------------------------

### Programmatically Export Demo Catalog Data

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/CHANGELOG.md

Import demo catalog data and types from `@dashcommerce/core` for use in custom seed scripts. This allows for cherry-picking specific demo data.

```javascript
import { DEMO_PRODUCTS, DEMO_PRODUCT_CATEGORY_TERMS, DEMO_PRODUCT_TAG_TERMS, DemoProductEntry, DemoTaxonomyTerm } from '@dashcommerce/core'
```

--------------------------------

### Configure EmDash with Dashcommerce Plugin

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/README.md

Configure EmDash with SQLite database, local storage, and the Dashcommerce plugin in astro.config.mjs.

```ts
import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { sqlite } from "emdash/db";
import { local } from "emdash/storage/local";
import { dashcommerce } from "@dashcommerce/core";

export default defineConfig({
  integrations: [
    emdash({
      database: sqlite({ url: "file:./data.db" }),
      storage: local({ directory: "./uploads", baseUrl: "/_emdash/api/media/file" }),
      plugins: [dashcommerce()],
    }),
  ],
});
```

--------------------------------

### Bootstrap Script for Seed Merge

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/core/README.md

Integrates the seed merging and EmDash seeding process into a package.json script for easy bootstrapping.

```json
"scripts": {
  "bootstrap": "dashcommerce-merge-seed && bun emdash seed --on-conflict=update"
}
```

--------------------------------

### Add Demo Catalog to Seed Data

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/README.md

Optionally add demo products and curated terms to your seed data by using the --with-demo-catalog flag.

```sh
bunx dashcommerce-merge-seed --with-demo-catalog
bun emdash seed --on-conflict=update
```

--------------------------------

### Add Demo Products to Seed Data

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/CHANGELOG.md

Use the `--with-demo-catalog` flag with the `dashcommerce-merge-seed` CLI to append demo products and terms. This operation is safe to re-run as it merges based on product ID.

```bash
dashcommerce-merge-seed --with-demo-catalog
```

--------------------------------

### Dashcommerce Astro Configuration

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/README.md

Shows how Dashcommerce is integrated into an Astro project via the emdash plugin.

```text
astro.config.mjs
  └─ emdash({ plugins: [dashcommerce()] })
       │
       ├─ Vite build ──► packages/core/src/index.ts          # descriptor only, side-effect-free
       │
       └─ Runtime    ──► packages/core/src/sandbox-entry.ts  # hooks + routes
                          │
                          ├─ routes/cart.ts        (public)
                          ├─ routes/checkout.ts   (public)
                          ├─ routes/webhook.ts    (public; Stripe-signed)
                          ├─ routes/admin-api.ts  (admin-gated)
                          └─ …12 more
```

--------------------------------

### Dashcommerce Core Package File Structure

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/RESUME.md

Overview of the file organization within the core package, detailing the purpose of each file and directory. This structure supports modularity and maintainability.

```tree
packages/core/src/
├── index.ts                     # native descriptor factory + re-exports
├── sandbox-entry.ts             # definePlugin({ hooks, routes }) — wired to content hook + cart routes
├── storage-collections.ts       # 19 plugin storage collections w/ indexes + uniqueIndexes
├── money.ts                     # Money type + arithmetic + format/parse; currency-safe; no floats
├── types.ts                     # full entity type surface (~470 LoC)
├── seed/products-collection.ts  # defineProductsCollection() helper for host seed.json
├── hooks/content.ts             # content:beforeSave product field validation
├── products/
│   ├── types.ts                 # purchasability + shipping predicates
│   ├── pricing.ts               # resolvePrice({ product, variant?, currency })
│   └── variants.ts              # variant CRUD against ctx.storage.product_variants
├── cart/
│   ├── store.ts                 # KV CRUD (cart:{sessionId})
│   └── calculate.ts             # subtotal → discount → shipping → tax → total pipeline (pure)
├── coupons/validate.ts          # validateCoupon + resolveDiscount (all 5 discount types)
├── shipping/calculate.ts        # flat / free / pickup / weight-based rate options per zone
├── tax/calculate.ts             # tax table engine (multi-rate, compound support)
├── stripe/
│   ├── client.ts                # ctx.http.fetch wrapper; urlencoded; Idempotency-Key; Connect header
│   ├── payment-intents.ts       # createPaymentIntent + retrievePaymentIntent
│   └── webhook-verify.ts        # verifyStripeSignature via crypto.subtle (Web Crypto)
├── routes/cart.ts               # public: GET /cart, POST /cart/items, /cart/currency, /cart/shipping-address
├── admin/entry.tsx              # React admin entry stub — empty pages + widgets maps
└── astro/index.ts               # blockComponents export stub
```

--------------------------------

### Provision Cloudflare Workers Resources

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/starter/README.md

Commands to create necessary resources like D1 database, R2 bucket, KV namespace, and secrets for Cloudflare Workers deployment. Ensure to copy the database_id and namespace id from the output.

```sh
wrangler d1 create dashcommerce-demo                 # copy the database_id from output
wrangler r2 bucket create dashcommerce-demo-media
wrangler kv namespace create SESSION                 # copy the namespace id from output
openssl rand -hex 32 | wrangler secret put EMDASH_AUTH_SECRET
openssl rand -hex 32 | wrangler secret put EMDASH_PREVIEW_SECRET
```

--------------------------------

### Merge Seed and Seed EmDash CLI

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/core/README.md

This command merges DashCommerce seed data and then seeds the EmDash database. Use `--on-conflict=update` for subsequent runs after schema changes.

```sh
# Typical one-liner after emdash init (fresh DB)
bunx dashcommerce-merge-seed && bun emdash seed --on-conflict=update
```

--------------------------------

### KV Namespaces

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/core/README.md

Details the Key-Value (KV) namespaces used by the plugin, prefixed with 'ctx.kv'. These are used for storing settings, cart data, stock locks, and other transient information.

```text
settings:*                  plugin configuration (tax mode, currencies, Stripe keys, etc.)
cart:{sessionId}            active carts (30-day TTL via cookie)
lock:{productId}:{variant}  stock soft-locks during checkout
abandoned:{sessionId}       abandoned-cart marker (sent / not sent)
email-throttle:{category}:* per-customer email de-duplication keys
```

--------------------------------

### Storefront API Routes

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/core/README.md

Publicly accessible routes for storefront interactions, including cart management, checkout, reviews, and configuration checks.

```APIDOC
## Storefront API Routes

All paths mount under `/_emdash/api/plugins/dashcommerce/`.

### GET /cart

**Description**: Retrieves the current cart. Creates a new cart if one does not exist and recalculates its contents.

### POST /cart/items

**Description**: Adds a new line item to the current cart.

### PATCH /cart/item?lineId={id}

**Description**: Updates the quantity of an existing line item in the cart. Requires the `lineId` of the item to update.

### DELETE /cart/item?lineId={id}

**Description**: Removes a line item from the cart. Requires the `lineId` of the item to remove.

### DELETE /cart/clear

**Description**: Empties the current cart while preserving the session.

### POST /cart/currency

**Description**: Switches the cart's currency. This operation is only allowed on an empty cart.

### POST /cart/coupon

**Description**: Applies a coupon to the current cart.

### DELETE /cart/coupon/remove?code={code}

**Description**: Removes a previously applied coupon from the cart. Requires the `code` of the coupon to remove.

### POST /cart/shipping-location

**Description**: Sets the shipping country and postal code for pre-flight checks in hosted checkout.

### POST /cart/shipping-address

**Description**: Sets the full shipping address for embedded checkout.

### POST /cart/contact

**Description**: Sets the customer's email address and billing address.

### POST /cart/shipping-methods

**Description**: Lists available shipping methods for the current shipping destination.

### POST /cart/shipping-method

**Description**: Selects a shipping method for the cart. Requires the `id` of the shipping method.

### GET /cart/restore?token={t}

**Description**: Recovers an abandoned cart using a provided token.

### POST /checkout/create-intent

**Description**: Creates a PaymentIntent for embedded Elements checkout.

### POST /checkout/create-session

**Description**: Creates a Checkout Session for hosted checkout.

### GET /checkout/mode

**Description**: Retrieves the active checkout mode (hosted or embedded).

### POST /checkout/webhook

**Description**: Receives Stripe webhooks, verifying their signatures.

### GET /orders/by-draft?id={draftId}

**Description**: Polls the status of an order after checkout using the draft ID.

### GET /downloads/serve?token={t}

**Description**: Delivers a file via a signed URL.

### GET /reviews/list?productId={id}

**Description**: Retrieves a paginated list of reviews for a given product ID.

### POST /reviews/item

**Description**: Submits a new review for moderation.

### GET /config-check

**Description**: Performs a read-only health check, verifying the presence of Stripe keys and other configurations.
```

--------------------------------

### Stripe Webhook Forwarding for Local Development

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/README.md

Configures Stripe CLI to forward webhooks to the local development server.

```sh
stripe listen --forward-to localhost:4321/_emdash/api/plugins/dashcommerce/checkout/webhook
```

--------------------------------

### Programmatically Merge Seed Data with Demo Catalog

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/CHANGELOG.md

Call `mergeDashCommerceSeed` programmatically to merge seed data, optionally including the demo catalog. This function mirrors the behavior of the CLI flag.

```javascript
mergeDashCommerceSeed(seed, { withDemoCatalog: true })
```

--------------------------------

### Handle Admin Reports Page Crash with No Orders

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/CHANGELOG.md

Guard `data.series` reads with `Array.isArray` and optional chaining for nested currency lookups. This prevents crashes when no paid orders exist, displaying an empty state instead.

```javascript
Array.isArray(data.series) && data.series.some(s => s.currencies?.[currency])
```

--------------------------------

### Seed D1 Database for Cloudflare Workers

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/starter/README.md

Command to seed the D1 database by dumping the local SQLite database and applying it to the remote D1 instance. This is a one-time operation performed from your local machine.

```sh
bun run cf:d1:seed       # dumps local SQLite → applies to D1
```

--------------------------------

### Public Storefront API Routes

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/core/README.md

These are the public-facing API endpoints for the storefront. They allow customers to interact with their carts, initiate checkouts, and manage other storefront-specific actions.

```http
GET    /cart                              Current cart (creates if missing; re-runs recalculate)
POST   /cart/items                        Add line item
PATCH  /cart/item?lineId={id}             Update qty
DELETE /cart/item?lineId={id}             Remove line
DELETE /cart/clear                        Empty cart (keeps session)
POST   /cart/currency                     Switch currency (empty cart only)
POST   /cart/coupon                       Apply coupon
DELETE /cart/coupon/remove?code={code}    Remove coupon
POST   /cart/shipping-location            Set country + postal (hosted checkout pre-flight)
POST   /cart/shipping-address             Full address (embedded checkout)
POST   /cart/contact                      Email + billing address
POST   /cart/shipping-methods             List rates for current ship-to
POST   /cart/shipping-method              Choose method id
GET    /cart/restore?token={t}            Abandoned-cart recovery link

POST   /checkout/create-intent            Embedded Elements: create PaymentIntent
POST   /checkout/create-session           Hosted Checkout: create Checkout Session
GET    /checkout/mode                     Which mode is active (hosted | embedded)
POST   /checkout/webhook                  Stripe webhook sink (signature-verified)

GET    /orders/by-draft?id={draftId}      Poll order status after checkout

GET    /downloads/serve?token={t}         Signed-URL download delivery

GET    /reviews/list?productId={id}       Paginated reviews
POST   /reviews/item                      Submit a review (moderation queue)

GET    /config-check                      Read-only health check (Stripe keys present, etc.)
```

--------------------------------

### Seed Remote Database for Railway Deployment

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/starter/README.md

Command to seed the remote database when deploying to Railway. This command is run once against the remote database.

```sh
railway run bun run bootstrap
```

--------------------------------

### Plugin Storage Collections

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/core/README.md

Lists the 19 storage collections declared within the plugin, used for persisting various e-commerce data. Note that the 'products' collection is hosted externally.

```text
orders · order_items · order_refunds · customers · customer_addresses
product_variants · inventory_ledger · stock_locks
coupons · coupon_usages · shipping_zones · shipping_methods · shipping_classes
tax_rates · reviews · subscriptions · vendors · vendor_payouts · download_grants
```

```text
products  (lives on host content, not plugin storage — emdash restriction)
```

--------------------------------

### Deploy Cloudflare Workers Application

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/starter/README.md

Command to deploy the Cloudflare Workers application, setting the required environment variables for D1 database and KV session ID. Alternatively, use the `wrangler deploy` command with a specific config file for hosted builds.

```sh
CF_D1_DATABASE_ID=… CF_KV_SESSION_ID=… bun run cf:deploy
```

```sh
npx wrangler deploy --config dist/server/wrangler.json
```

--------------------------------

### Register Dashcommerce Plugin in Astro Config

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/README.md

Register the Dashcommerce plugin within your Astro configuration file.

```ts
import { dashcommerce } from "@dashcommerce/core";

emdash({ plugins: [dashcommerce()] });
```

--------------------------------

### Admin API Routes

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/core/README.md

Routes accessible only to administrators, covering settings management, order processing, customer management, and reporting.

```APIDOC
## Admin-gated Routes

Same prefix (`/_emdash/api/plugins/dashcommerce/`), gated by emdash's admin auth.

### GET /admin/settings

**Description**: Reads all administrative settings.

### POST /admin/settings

**Description**: Writes administrative settings, validated against a schema.

### POST /admin/stripe/ping

**Description**: Performs a sanity check on the live Stripe keys.

### GET /admin/orders, /admin/orders/:id

**Description**: Retrieves a list of orders or details for a specific order by ID.

### POST /admin/orders/:id/refund

**Description**: Processes a full or partial refund for a given order.

### PATCH /admin/orders/:id/status

**Description**: Transitions the status of an order, potentially triggering review requests or other workflows.

### GET /admin/customers

**Description**: Provides Customer CRUD (Create, Read, Update, Delete) operations.

### GET /admin/reports/revenue

**Description**: Retrieves revenue reports sliced by date range, with comparison data.

### GET /admin/reports/top-products

**Description**: Lists top-selling products by quantity or revenue.

### GET /admin/reports/top-customers

**Description**: Generates a leaderboard of top customers based on lifetime value.

### GET /admin/reports/mrr

**Description**: Calculates and retrieves Monthly Recurring Revenue (MRR) by currency.

**Note**: The documentation also mentions additional admin functionalities for coupons, vendors, shipping zones/methods, tax rates, subscriptions, review moderation, menus, and customer portal sessions, but specific endpoints are not detailed.
```

--------------------------------

### Configure Node Built-ins as Externals

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/CHANGELOG.md

Mark Node built-ins as explicit externals in tsdown config to resolve UNRESOLVED_IMPORT warnings in the Node-only CLI entry. Sandbox-safety is maintained.

```javascript
externals: [
  /^node:/,
]
```

--------------------------------

### Admin-Gated API Routes

Source: https://github.com/emdashcommerce/dashcommerce/blob/main/packages/core/README.md

These API endpoints are protected by admin authentication. They provide access to administrative functions such as managing settings, orders, customers, and reports.

```http
GET    /admin/settings                    Read all settings:* keys
POST   /admin/settings                    Write (validated via schema)
POST   /admin/stripe/ping                 Live-key sanity check
GET    /admin/orders, /admin/orders/:id   Order list + detail
POST   /admin/orders/:id/refund           Full or partial refund
PATCH  /admin/orders/:id/status           Transition order status (triggers review-request etc.)
GET    /admin/customers …                 Customer CRUD
GET    /admin/reports/revenue             Range-sliced revenue with comparison
GET    /admin/reports/top-products        Best sellers by qty or revenue
GET    /admin/reports/top-customers       Lifetime-value leaderboard
GET    /admin/reports/mrr                 Active subscription MRR by currency
… plus coupons, vendors, shipping zones/methods, tax rates, subscriptions, reviews moderation, menu, customer-portal-session
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.