Skip to content
Emdash Mika Docs

Copy Paths

Start with the ⓐ copyable Astro template files, then copy only what the host app needs. They live in ../emdash-mika/src/templates/astro/** and are published through the package ./templates/astro/* export. The copied files become normal host files in src/actions/, src/components/, src/pages/, src/lib/, and src/styles/.

New hosts do not need to copy lib/form.ts; hidden-input helpers are exported from @bnomei/emdash-mika/astro.

Choose the smallest scenario first:

Scenario Copy first Then read
One product page Actions, Kumo shell, purchase components, structured data, route/display helpers. First Product Page
Full buyer storefront Product set plus cart, wishlist, checkout returns, account, downloads, and webhook pages. Astro Storefront
Public agent metadata ProductStructuredData.astro, pages/llms.txt.ts, and pages/.well-known/mika-agent.json.ts. Agent-Ready Storefront

Core product flow:

  • actions/index.ts and actions/mika.ts register actions.mika.*;
  • styles/kumo.css, MikaKumoAppFrame.tsx, and MikaKumoPage.astro provide the copied Kumo shell;
  • ProductPurchase.astro owns variant choice, quantity limits, add-to-cart, buy-now, and wishlist forms;
  • ProductStructuredData.astro emits JSON-LD that should match visible product state.

Minimum product-copy set:

actions/index.ts -> src/actions/index.ts
actions/mika.ts -> src/actions/mika.ts
styles/kumo.css -> src/styles/kumo.css
components/MikaKumoAppFrame.tsx -> src/components/MikaKumoAppFrame.tsx
components/MikaKumoPage.astro -> src/components/MikaKumoPage.astro
components/ProductPurchase.astro -> src/components/ProductPurchase.astro
components/ProductPurchaseSync.astro -> src/components/ProductPurchaseSync.astro
components/AddToCartForm.astro -> src/components/AddToCartForm.astro
components/AddToCartFormSync.astro -> src/components/AddToCartFormSync.astro
components/BuyNowForm.astro -> src/components/BuyNowForm.astro
components/WishlistForm.astro -> src/components/WishlistForm.astro
components/VariantOptionGroups.astro -> src/components/VariantOptionGroups.astro
components/VariantSelector.astro -> src/components/VariantSelector.astro
components/StockBadge.astro -> src/components/StockBadge.astro
components/LowStockNotice.astro -> src/components/LowStockNotice.astro
components/UnavailableNotice.astro -> src/components/UnavailableNotice.astro
components/ProductStructuredData.astro -> src/components/ProductStructuredData.astro
lib/routes.ts -> src/lib/routes.ts
lib/display.ts -> src/lib/display.ts
lib/cart.ts -> src/lib/cart.ts

lib/routes.ts matters even for the product flow because BuyNowForm.astro defaults its checkout success and cancel paths from mikaTemplateRoutes. If the host does not copy the default checkout pages, pass successPath and cancelPath from the host product page instead.

Full storefront flow:

  • cart and wishlist pages read request-bound state with createMika(Astro);
  • checkout success confirms status, while checkout cancel can abandon the checkout but does not prove payment state;
  • account pages use magic-link, order, subscription, license, download, export, delete, and portal actions;
  • downloads and webhooks are host endpoints, not public plugin mutation routes.

Agent-readable flow:

  • ProductStructuredData.astro;
  • pages/llms.txt.ts;
  • pages/.well-known/mika-agent.json.ts.

Next: Astro Template File Map shows the full tree. Astro Template Files is the canonical exact copy matrix.

Where The Examples Come From

Section titled “Where The Examples Come From”

The package template directory ../emdash-mika/src/templates/astro/** is the canonical copy source. Its README explains the groups, but the source tree can include files that are newer or more detailed than that README. The runnable seeded repo at ../emdash-mika-template is a worked host app that has already copied and adapted those files. Use the seeded repo to inspect behavior, but treat the package template directory and package export as the copy source.

External References

Section titled “External References”

Source Anchors

Section titled “Source Anchors”
  • ⓐ ../emdash-mika/src/templates/astro/README.md
  • ⓐ ../emdash-mika/src/templates/astro/components/ProductPurchase.astro
  • ⓐ ../emdash-mika/src/templates/astro/components/AddToCartForm.astro
  • ⓐ ../emdash-mika/src/templates/astro/components/BuyNowForm.astro
  • ⓐ ../emdash-mika/src/templates/astro/lib/routes.ts
  • ⓟ ../emdash-mika/package.json
  • ⓣ ../emdash-mika-template/src/actions/index.ts
  • ⓣ ../emdash-mika-template/src/pages/cart.astro