starter-astro — Astro 电商模板

SHA-256: b1c7e2399d236a2443c17ec7e88b38962675c61743d683890ecae4cd1d9f1237

2026-10-02T07:35:56.940Z

# WireGum × Astro starter

A small, production-minded storefront starter for [Astro](https://astro.build) and [WireGum](https://wiregum.com).

Astro owns the editorial layer: pages, copy and product imagery live in Markdown content collections and are rendered to static HTML at build time. WireGum provides live prices, variants, cart state and Stripe Checkout through its storefront widget. Stripe handles the payments.

Read the full integration guide at [wiregum.com/docs/astro](https://wiregum.com/docs/astro).

## What is included

- A home page with a hero, a "how it works" section and featured products picked in frontmatter
- A shop index with quick add-to-cart, and product pages with live prices and variant selectors
- An accessible, fully themeable cart drawer
- Graceful degradation: the widget checks that the storefront API is reachable from the current origin. If it is not, Astro's images, copy and fallback prices stay visible and the buy buttons are disabled. No widget error replaces your content
- Four seeded demo products, including a t-shirt with Size and Color variants, wired to the public WireGum demo workspace
- Tailwind CSS v4 with a small token set (Mona Sans, warm paper palette, WireGum pink as the single accent) and a few small dependency-free component scripts

## Requirements

- Node.js 22.12 or newer
- A WireGum workspace with the storefront domain authorized

## Quick start

```sh
npm install
npm run dev
```

Open `http://localhost:4321` for the storefront. `npm run build` renders the static site into `dist/`, and `npm run preview` serves that build locally.

### About the demo workspace

The seeded content points at the public WireGum demo workspace, which authorizes the hosted demo at `https://starter-astro.wiregum.com`. On any other origin, including local development, the demo runs in fallback mode by design: Astro's content and fallback prices stay visible while **Add to cart** and checkout are disabled. Connect your own workspace and authorize your local or production origin to lift that.

## Connect your own workspace

WireGum settings live in [src/lib/wiregum.ts](src/lib/wiregum.ts) and can be overridden per environment with a `.env` file (see [.env.example](.env.example)):

| Env var                       | What it is                                                                                            |
| ----------------------------- | ----------------------------------------------------------------------------------------------------- |
| `PUBLIC_WIREGUM_WIDGET_URL`   | The storefront widget URL for your WireGum instance, e.g. `https://wiregum.com/api/storefront/widget` |
| `PUBLIC_WIREGUM_ORGANIZATION` | Your workspace slug, from the WireGum dashboard                                                       |
| `PUBLIC_WIREGUM_LOCALE`       | The storefront locale, e.g. `en` or `it`                                                              |

Then:

1. In WireGum → Storefront settings, authorize the exact origin your site runs on (including `localhost:4321` for local work) and add at least one shipping rate
2. In each product's frontmatter, set `wiregumProduct` to a reference from WireGum → Products: either the public ID (`wg_…`) or the product slug. The ID survives renames, the slug is easier to read; this starter uses the IDs
3. Set `site` in [astro.config.mjs](astro.config.mjs) to the production origin used for canonical and Open Graph URLs
4. Replace the demo product IDs and imagery before using the starter for a real store

## How the integration works

- [src/layouts/Layout.astro](src/layouts/Layout.astro) embeds the WireGum settings as a JSON `data-wiregum-config` block and loads the widget script; no custom JavaScript is needed
- The widget reads the config, hydrates the commerce markup, and exposes its lifecycle on `<html data-wiregum-status>` (`loading`, `ready`, `unavailable`) for the CSS skeleton. When the origin is not authorized it keeps the Astro markup intact and disables the buy buttons instead
- Templates mark up commerce hooks with `data-wiregum-*` attributes: the product scope ([src/pages/shop/[slug].astro](src/pages/shop/[slug].astro)), prices, the variant selector, quantity and add-to-cart
- The cart drawer ([src/components/CartDrawer.astro](src/components/CartDrawer.astro)) contains a hidden `data-wiregum-cart-item` template the widget clones for every line, keeping the markup fully themeable
- The widget renders variant selectors automatically for multi-variant products, as shown by the seeded t-shirt

The key integration points carry short code comments explaining each pattern.

## Editing content

Everything editorial lives in [src/content/products](src/content/products): one Markdown file per product, with title, short description, cover image, fallback price, CTA label and the WireGum reference in frontmatter, and the long description in the body. Home and shop copy live in their page templates.

## Project structure

```text
src/styles/global.css        Design tokens and WireGum widget styling (Tailwind v4)
src/content/products/        Seeded products (Markdown + frontmatter)
src/assets/products/         Demo product images, optimized by astro:assets
src/lib/                     Site identity and WireGum settings
src/layouts/Layout.astro     Head, WireGum config + widget script, page chrome
src/components/              Header, footer, ticker, product card/row, cart drawer
src/pages/                   Home, shop index, product pages, 404
public/fonts/                Mona Sans variable font (OFL)
```

## Deploying

`npm run build` produces a fully static site in `dist/` — deploy it to any static host (Netlify, Vercel, Cloudflare Pages, GitHub Pages, your own server). Set the `PUBLIC_WIREGUM_*` env vars at build time for the target environment. Remember to authorize the production origin in WireGum.

## Links

- [WireGum](https://wiregum.com) · [Astro guide](https://wiregum.com/docs/astro) · [GitHub](https://github.com/getwiregum)
- [Astro](https://astro.build)

## License

The starter code (templates, components, content, styles and scripts) is [MIT-licensed](LICENSE).

[Mona Sans](https://github.com/github/mona-sans) is included under the SIL Open Font License (see [public/fonts/MonaSans-OFL.txt](public/fonts/MonaSans-OFL.txt)).