{"id":46963630,"url":"https://github.com/decocms/apps-start","last_synced_at":"2026-05-19T00:09:38.188Z","repository":{"id":343660907,"uuid":"1167704908","full_name":"decocms/apps-start","owner":"decocms","description":"Deco commerce apps for TanStack Start - Shopify, VTEX, commerce types","archived":false,"fork":false,"pushed_at":"2026-05-01T14:50:52.000Z","size":1909,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T15:26:08.972Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/decocms.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-26T15:37:58.000Z","updated_at":"2026-05-01T14:50:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/decocms/apps-start","commit_stats":null,"previous_names":["decocms/apps-start"],"tags_count":42,"template":false,"template_full_name":null,"purl":"pkg:github/decocms/apps-start","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decocms%2Fapps-start","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decocms%2Fapps-start/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decocms%2Fapps-start/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decocms%2Fapps-start/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/decocms","download_url":"https://codeload.github.com/decocms/apps-start/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decocms%2Fapps-start/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32503204,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-11T10:07:08.976Z","updated_at":"2026-05-19T00:09:38.174Z","avatar_url":"https://github.com/decocms.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @decocms/apps\n\n[![npm version](https://img.shields.io/npm/v/@decocms/apps.svg)](https://www.npmjs.com/package/@decocms/apps)\n[![license](https://img.shields.io/npm/l/@decocms/apps.svg)](https://github.com/decocms/apps-start/blob/main/LICENSE)\n\nCommerce integrations for [deco.cx](https://deco.cx) storefronts on **TanStack Start + React 19 + Cloudflare Workers**.\n\n`@decocms/apps` provides VTEX, Shopify, and Resend integrations (loaders, actions, hooks, middleware) plus shared schema.org commerce types. It depends on [`@decocms/start`](https://www.npmjs.com/package/@decocms/start).\n\n📖 **[Read the full documentation →](https://docs.deco.cx/v2/en/commerce/overview)**\n\n---\n\n## Install\n\n```bash\nnpm install @decocms/apps\n```\n\n### Release channels\n\n`@decocms/apps` publishes two npm dist-tags:\n\n- **`@latest`** — default channel. `npm install @decocms/apps` and any `^X.Y.Z` range resolve here.\n- **`@next`** — opt-in prerelease channel for validation builds (`X.Y.Z-next.N`). Carets never resolve to prereleases, so you only get these by asking:\n\n  ```bash\n  # Follow the next channel (re-resolves on each install)\n  npm install @decocms/apps@next\n\n  # Or pin an exact prerelease\n  npm install @decocms/apps@1.14.0-next.0\n  ```\n\n---\n\n## Minimum wiring\n\n### VTEX\n\nA working VTEX storefront needs three things: a `deco-vtex` config block, an `initVtexFromBlocks()` call in setup, and the commerce loader registry.\n\n#### 1. Config block (`.deco/blocks/deco-vtex.json`)\n\n```json\n{\n  \"__resolveType\": \"deco-vtex\",\n  \"account\": \"my-store\",\n  \"publicUrl\": \"https://www.my-store.com.br\",\n  \"salesChannel\": \"1\",\n  \"appKey\": { \"__resolveType\": \"secret/key\" },\n  \"appToken\": { \"__resolveType\": \"secret/key\" }\n}\n```\n\n#### 2. Setup (`src/setup.ts`)\n\n```ts\nimport { createSiteSetup } from \"@decocms/start/setup\";\nimport { createInstrumentedFetch } from \"@decocms/start/sdk/instrumentedFetch\";\nimport { initVtexFromBlocks, setVtexFetch } from \"@decocms/apps/vtex/client\";\nimport { createVtexCommerceLoaders } from \"@decocms/apps/vtex/commerceLoaders\";\n\ncreateSiteSetup({\n  sections: import.meta.glob(\"./sections/**/*.tsx\", { eager: true }),\n  blocks,\n  meta: () =\u003e meta,\n  initPlatform: () =\u003e initVtexFromBlocks(),\n  getCommerceLoaders: () =\u003e createVtexCommerceLoaders(),\n});\n\nsetVtexFetch(createInstrumentedFetch(\"vtex\"));\n```\n\n#### 3. Hooks in components\n\n```tsx\nimport { useCart, useUser, useWishlist } from \"@decocms/apps/vtex/hooks\";\n\nfunction AddToCartButton({ sku }: { sku: string }) {\n  const { addItems, isMutating } = useCart();\n  return (\n    \u003cbutton\n      onClick={() =\u003e addItems([{ id: sku, quantity: 1 }])}\n      disabled={isMutating}\n    \u003e\n      Add to cart\n    \u003c/button\u003e\n  );\n}\n```\n\nThat's it. Loaders are auto-registered, hooks are typed, edge cache + cookie propagation work out of the box.\n\n### Shopify\n\n```ts\nimport { createSiteSetup } from \"@decocms/start/setup\";\nimport { initShopifyFromBlocks } from \"@decocms/apps/shopify/client\";\nimport { createShopifyCommerceLoaders } from \"@decocms/apps/shopify/commerceLoaders\";\n\ncreateSiteSetup({\n  sections: import.meta.glob(\"./sections/**/*.tsx\", { eager: true }),\n  blocks,\n  meta: () =\u003e meta,\n  initPlatform: () =\u003e initShopifyFromBlocks(),\n  getCommerceLoaders: () =\u003e createShopifyCommerceLoaders(),\n});\n```\n\nConfig block (`deco-shopify`) needs `storeName`, `storefrontAccessToken`, `languageCode`, `countryCode`.\n\n\u003e ⚠️ Shopify cart loaders require **cart-cookie wiring** in your route handler. See [Shopify reference](https://docs.deco.cx/v2/en/commerce/shopify) for the canonical pattern.\n\n### Resend\n\n```ts\nimport { initResendFromBlocks } from \"@decocms/apps/resend/client\";\nimport { sendEmail } from \"@decocms/apps/resend/sdk\";\n\nawait sendEmail({\n  to: \"customer@example.com\",\n  subject: \"Order confirmed\",\n  html: \"\u003ch1\u003eThanks!\u003c/h1\u003e\",\n});\n```\n\n---\n\n## What's exported\n\n### VTEX\n\n| Subpath | Purpose |\n|---------|---------|\n| `@decocms/apps/vtex` | Barrel index |\n| `@decocms/apps/vtex/client` | `vtexFetch`, `vtexFetchWithCookies`, `intelligentSearch`, `setVtexFetch`, `initVtexFromBlocks`, `configureVtex` |\n| `@decocms/apps/vtex/commerceLoaders` | `createVtexCommerceLoaders` |\n| `@decocms/apps/vtex/loaders/*` | Cart, user, wishlist, search, catalog, sessions, orders, autocomplete |\n| `@decocms/apps/vtex/actions/*` | Cart mutations, auth, profile, address, wishlist, newsletter |\n| `@decocms/apps/vtex/hooks` | `useCart`, `useUser`, `useWishlist`, `useAutocomplete`, plus `createUseCart` / `createUseUser` / `createUseWishlist` factories |\n| `@decocms/apps/vtex/inline-loaders/*` | PDP, PLP, shelves, suggestions, minicart |\n| `@decocms/apps/vtex/middleware` | `extractVtexContext`, `vtexCacheKeySuffix`, `propagateISCookies`, `createVtexCheckoutProxy` |\n| `@decocms/apps/vtex/utils/*` | Transform, segment, cookies, slugCache, sortwhitelist |\n\n\u003e 💡 **Calling VTEX loaders/actions from the client.** Use the typed `invoke` client generated by `@decocms/start` — `invoke[\"vtex/loaders/cart.ts\"](props)` — or use the React hooks above. There is **no** `@decocms/apps/vtex/invoke` subpath.\n\n### Shopify\n\n| Subpath | Purpose |\n|---------|---------|\n| `@decocms/apps/shopify` | Barrel |\n| `@decocms/apps/shopify/client` | `setShopifyFetch`, GraphQL helpers |\n| `@decocms/apps/shopify/loaders/*` | PDP, PLP, ProductList, RelatedProducts, Cart, Account |\n| `@decocms/apps/shopify/actions/cart/*` | `addItems`, `updateItems`, `discountCodesUpdate` |\n| `@decocms/apps/shopify/actions/user/*` | `signIn`, `signUp` |\n| `@decocms/apps/shopify/utils/*` | Transform, cookies, GraphQL queries |\n\n### Resend\n\n| Subpath | Purpose |\n|---------|---------|\n| `@decocms/apps/resend/client` | `initResendFromBlocks` |\n| `@decocms/apps/resend/sdk` | `sendEmail` |\n| `@decocms/apps/resend/actions/send` | Invocable email action |\n\n### Shared commerce\n\nPlatform-agnostic types and components.\n\n| Subpath | Purpose |\n|---------|---------|\n| `@decocms/apps/commerce/types` | schema.org `Product`, `ProductDetailsPage`, `ProductListingPage`, `Offer`, `BreadcrumbList`, etc. |\n| `@decocms/apps/commerce/components/Image` | Optimized commerce image with CDN routing |\n| `@decocms/apps/commerce/components/Picture` | `\u003cpicture\u003e` with responsive sources |\n| `@decocms/apps/commerce/components/JsonLd` | Structured data for SEO |\n| `@decocms/apps/commerce/sdk/useOffer` | Pick the best offer per region/seller |\n| `@decocms/apps/commerce/sdk/format` | `formatPrice`, `formatPriceRange` |\n| `@decocms/apps/commerce/sdk/analytics` | Event types + `mapProductToAnalyticsItem` |\n| `@decocms/apps/commerce/sdk/useVariantPossibilities` | Variant axis builder for selectors |\n\n### Website (utility app)\n\n| Subpath | Purpose |\n|---------|---------|\n| `@decocms/apps/website` | `configureWebsite`, `configureSeo` |\n| `@decocms/apps/website/loaders/redirectsFromCsv` | Bulk redirects from CSV |\n| `@decocms/apps/website/loaders/fonts/*` | Google fonts, custom CDN font loaders |\n\nComplete export tables: [docs.deco.cx/v2/en/reference/commerce-exports](https://docs.deco.cx/v2/en/reference/commerce-exports).\n\n---\n\n## Documentation\n\nThe commerce documentation lives at **[docs.deco.cx/v2/en/commerce](https://docs.deco.cx/v2/en/commerce/overview)**:\n\n- [VTEX overview](https://docs.deco.cx/v2/en/commerce/vtex-overview) — config block, secrets, install steps.\n- [VTEX loaders \u0026 actions](https://docs.deco.cx/v2/en/commerce/vtex-loaders-and-actions) — input/output cookbook.\n- [VTEX hooks](https://docs.deco.cx/v2/en/commerce/vtex-hooks) — `useCart`, `useUser`, `useWishlist`, `useAutocomplete`.\n- [VTEX gotchas](https://docs.deco.cx/v2/en/commerce/vtex-gotchas) — cookies, sales channel, regionId, IS sort sanitization.\n- [Shopify](https://docs.deco.cx/v2/en/commerce/shopify) — configure, loaders, actions, cart-cookie wiring.\n- [Resend](https://docs.deco.cx/v2/en/commerce/resend) — email setup.\n\n---\n\n## Peer dependencies\n\n```json\n{\n  \"@decocms/start\": \"\u003e=2.0.0\",\n  \"@tanstack/react-query\": \"\u003e=5.0.0\",\n  \"react\": \"\u003e=19.0.0\",\n  \"react-dom\": \"\u003e=19.0.0\"\n}\n```\n\nThe published peer floor is React 18 to ease incremental migration, but the v2 stack assumes React 19 + the React Compiler.\n\n---\n\n## Development\n\n```bash\nnpm run typecheck   # tsc --noEmit\nnpm run check       # typecheck + unused export detection\n```\n\nThis is a library — there is no dev server. Consumer storefronts run their own `vite dev`.\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecocms%2Fapps-start","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdecocms%2Fapps-start","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecocms%2Fapps-start/lists"}