Skip to content
Emdash Mika Docs

First Integration Checklist

Use this checklist when starting from an existing Astro + EmDash app. It is the bridge between Getting Started and the deeper implementation guides.

Stop after the first product page works. Add cart, wishlist, account, downloads, webhooks, admin actions, and agent metadata only when the host needs those flows.

  1. Confirm package state and peer ranges in Compatibility And Publication.
  2. Install or link @bnomei/emdash-mika, and pin EmDash inside Mika’s current peer range.
  3. Register EmDash and Mika in astro.config.mjs.
  4. Create src/lib/mika-api.ts with either fixture overrides or a production createMikaBackendApi() composition.
  5. Copy templates/astro/actions/index.ts to src/actions/index.ts.
  6. Copy templates/astro/actions/mika.ts to src/actions/mika.ts.
  7. Install copied UI dependencies if you copy the Kumo-backed templates.
  8. Copy product purchase components plus src/styles/kumo.css.
  9. Build a host product route that resolves the slug to a stable content ref, then calls createMika(Astro).
  10. Add cart, wishlist, account, checkout-return, download, webhook, and metadata pages only when those flows are part of the host app.
  11. Run typecheck/build and smoke the browser paths.

Copy Commands

Section titled “Copy Commands”

From a host app after a package install, copy from the package export path:

Terminal window
mkdir -p src/actions src/components src/lib src/styles
cp node_modules/@bnomei/emdash-mika/src/templates/astro/actions/index.ts src/actions/index.ts
cp node_modules/@bnomei/emdash-mika/src/templates/astro/actions/mika.ts src/actions/mika.ts
cp node_modules/@bnomei/emdash-mika/src/templates/astro/styles/kumo.css src/styles/kumo.css
cp node_modules/@bnomei/emdash-mika/src/templates/astro/lib/routes.ts src/lib/routes.ts
cp node_modules/@bnomei/emdash-mika/src/templates/astro/components/ProductPurchase.astro src/components/ProductPurchase.astro
cp node_modules/@bnomei/emdash-mika/src/templates/astro/components/ProductPurchaseSync.astro src/components/ProductPurchaseSync.astro
cp node_modules/@bnomei/emdash-mika/src/templates/astro/components/AddToCartForm.astro src/components/AddToCartForm.astro
cp node_modules/@bnomei/emdash-mika/src/templates/astro/components/AddToCartFormSync.astro src/components/AddToCartFormSync.astro
cp node_modules/@bnomei/emdash-mika/src/templates/astro/components/BuyNowForm.astro src/components/BuyNowForm.astro
cp node_modules/@bnomei/emdash-mika/src/templates/astro/components/WishlistForm.astro src/components/WishlistForm.astro
cp node_modules/@bnomei/emdash-mika/src/templates/astro/components/VariantOptionGroups.astro src/components/VariantOptionGroups.astro
cp node_modules/@bnomei/emdash-mika/src/templates/astro/components/VariantSelector.astro src/components/VariantSelector.astro
cp node_modules/@bnomei/emdash-mika/src/templates/astro/components/StockBadge.astro src/components/StockBadge.astro
cp node_modules/@bnomei/emdash-mika/src/templates/astro/components/LowStockNotice.astro src/components/LowStockNotice.astro
cp node_modules/@bnomei/emdash-mika/src/templates/astro/components/UnavailableNotice.astro src/components/UnavailableNotice.astro
cp node_modules/@bnomei/emdash-mika/src/templates/astro/components/ProductStructuredData.astro src/components/ProductStructuredData.astro

In this local workspace, replace node_modules/@bnomei/emdash-mika/src/templates/astro with ../emdash-mika/src/templates/astro if the package is not installed from npm yet.

Config Skeleton

Section titled “Config Skeleton”

If you use the Node adapter shown below, run npm install @astrojs/node. Otherwise keep the host’s existing server adapter import and adapter option.

astro.config.mjs
import { defineConfig } from "astro/config";
import node from "@astrojs/node"; // Or keep the host's existing server adapter.
import emdash from "emdash/astro";
import { mikaPlugin } from "@bnomei/emdash-mika";
import { api } from "./src/lib/mika-api";


export default defineConfig({
  output: "server",
  adapter: node({ mode: "standalone" }),
  integrations: [
    emdash({
      plugins: [mikaPlugin({ api })],
    }),
  ],
});

Use a native entrypoint (mikaPlugin({ entrypoint: "#mika-plugin" })) when api is made of local functions or runtime-only modules that should not be serialized through descriptor options.

Verification

Section titled “Verification”

Minimum verification for the first slice:

  • the host build can resolve all copied component imports;
  • actions.mika.cart.add is registered and an add-to-cart form posts without an Action lookup error;
  • a product page calls Mika.catalog.sellables(collection, id) with the host content ref;
  • ProductStructuredData receives the same sellables shown to the buyer;
  • /_emdash/api/plugins/mika/catalog/sellables?collection=products&id=<product-id> returns a Mika result envelope for a real host content ref;
  • /_emdash/api/plugins/mika/sellables/availability?sellableId=<sellable-id> returns availability for a real sellable;
  • any copied request-bound page exports prerender = false or the app uses output: "server".

Next: Product Authoring clarifies the content-to-sellable mapping. Astro Storefront explains the copied UI and Actions in detail. Backend And Provider explains trusted backend wiring once fixture overrides are not enough.

Source Anchors

Section titled “Source Anchors”
  • ⓐ ../emdash-mika/src/templates/astro/actions/index.ts
  • ⓐ ../emdash-mika/src/templates/astro/actions/mika.ts
  • ⓐ ../emdash-mika/src/templates/astro/components/ProductPurchase.astro
  • ⓐ ../emdash-mika/src/templates/astro/components/ProductStructuredData.astro
  • ⓐ ../emdash-mika/src/templates/astro/README.md
  • ⓟ ../emdash-mika/src/plugin.ts
  • ⓟ ../emdash-mika/src/astro-actions.ts
  • ⓣ ../emdash-mika-template/astro.config.mjs
  • ⓣ ../emdash-mika-template/src/pages/products/[slug].astro