{"id":46886424,"url":"https://github.com/decocms/deco-start","last_synced_at":"2026-07-02T14:06:08.892Z","repository":{"id":343558029,"uuid":"1167704887","full_name":"decocms/deco-start","owner":"decocms","description":"Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation","archived":false,"fork":false,"pushed_at":"2026-07-02T02:44:01.000Z","size":3412,"stargazers_count":4,"open_issues_count":21,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T04:25:05.651Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/decocms.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","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:56.000Z","updated_at":"2026-07-02T02:43:34.000Z","dependencies_parsed_at":null,"dependency_job_id":"7ec45eae-ba87-47c3-81e5-28722d98fb70","html_url":"https://github.com/decocms/deco-start","commit_stats":null,"previous_names":["decocms/deco-start"],"tags_count":255,"template":false,"template_full_name":null,"purl":"pkg:github/decocms/deco-start","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decocms%2Fdeco-start","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decocms%2Fdeco-start/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decocms%2Fdeco-start/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decocms%2Fdeco-start/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/decocms","download_url":"https://codeload.github.com/decocms/deco-start/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decocms%2Fdeco-start/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35050120,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-02T02:00:06.368Z","response_time":173,"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-10T22:10:00.319Z","updated_at":"2026-07-02T14:06:08.866Z","avatar_url":"https://github.com/decocms.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @decocms/start\n\n[![npm version](https://img.shields.io/npm/v/@decocms/start.svg)](https://www.npmjs.com/package/@decocms/start)\n[![license](https://img.shields.io/npm/l/@decocms/start.svg)](https://github.com/decocms/deco-start/blob/main/LICENSE)\n\nFramework layer for [deco.cx](https://deco.cx) storefronts on **TanStack Start + React 19 + Cloudflare Workers**.\n\n`@decocms/start` is the npm package that storefronts depend on. It provides the CMS bridge, admin protocol, section registry, schema generation, edge caching, the Vite plugin, and a small SDK. It is **not** itself a storefront — it is what storefronts build on top of.\n\n📖 **[Read the full documentation →](https://docs.deco.cx/v2/en/getting-started/overview)**\n\n---\n\n## What's in the box\n\n```\n┌─────────────────────────────────────────────────┐\n│   Site repo (your storefront)                    │  ← Components, sections, routes\n├─────────────────────────────────────────────────┤\n│   @decocms/apps  (commerce integrations)         │  ← VTEX, Shopify, Resend\n├─────────────────────────────────────────────────┤\n│   @decocms/start  (framework — this package)     │  ← CMS bridge, admin, caching\n└─────────────────────────────────────────────────┘\n              ↓ runs on ↓\n   TanStack Start  +  React 19  +  Cloudflare Workers\n```\n\n`@decocms/start` exports cover four surfaces:\n\n- **Worker entry** — `createDecoWorkerEntry` wraps your Cloudflare Worker with admin routes, edge cache, and asset bypass.\n- **CMS bridge** — `loadCmsPage`, `resolveDecoPage`, `registerSectionLoaders`, `registerLayoutSections`.\n- **Admin protocol** — `handleMeta`, `handleDecofile`, `handleRender`, `handleInvoke`.\n- **SDK** — `createCachedLoader`, `createInstrumentedFetch`, `createInvoke`, `decoVitePlugin`, plus utilities (cookies, redirects, sitemap, A/B testing).\n\nFull export reference: [docs.deco.cx/v2/en/reference/package-exports](https://docs.deco.cx/v2/en/reference/package-exports).\n\n---\n\n## Hello, World\n\nA minimal v2 storefront has six files. Here they are.\n\n### `package.json`\n\n```jsonc\n{\n  \"name\": \"my-store\",\n  \"type\": \"module\",\n  \"scripts\": {\n    \"dev\": \"vite dev\",\n    \"build\": \"vite build\",\n    \"deploy\": \"wrangler deploy\"\n  },\n  \"dependencies\": {\n    \"@decocms/start\": \"^2.28.0\",\n    \"@decocms/apps\": \"^1.11.0\",\n    \"@tanstack/react-start\": \"^1.166.0\",\n    \"react\": \"^19.0.0\",\n    \"react-dom\": \"^19.0.0\"\n  },\n  \"devDependencies\": {\n    \"vite\": \"^6.0.0\",\n    \"wrangler\": \"^4.72.0\"\n  }\n}\n```\n\n### `vite.config.ts`\n\n```ts\nimport { defineConfig } from \"vite\";\nimport { cloudflare } from \"@cloudflare/vite-plugin\";\nimport { tanstackStart } from \"@tanstack/react-start/plugin/vite\";\nimport react from \"@vitejs/plugin-react\";\nimport decoVitePlugin from \"@decocms/start/vite\";\n\nexport default defineConfig({\n  plugins: [\n    cloudflare({ viteEnvironment: { name: \"ssr\" } }),\n    tanstackStart({ server: { entry: \"server\" } }),\n    react({ babel: { plugins: [\"babel-plugin-react-compiler\"] } }),\n    decoVitePlugin(),\n  ],\n  resolve: {\n    alias: { \"~\": \"/src\" },\n    deduplicate: [\"react\", \"react-dom\", \"@decocms/start\", \"@decocms/apps\"],\n  },\n});\n```\n\n### `wrangler.jsonc`\n\n```jsonc\n{\n  \"name\": \"my-store\",\n  \"main\": \"./src/worker-entry.ts\",\n  \"compatibility_date\": \"2026-02-14\",\n  \"compatibility_flags\": [\n    \"nodejs_compat\",\n    \"no_handle_cross_request_promise_resolution\"\n  ],\n  \"assets\": { \"directory\": \"./dist/client\" }\n}\n```\n\n### `src/setup.ts`\n\n```ts\nimport { createSiteSetup } from \"@decocms/start/setup\";\nimport { applySectionConventions } from \"@decocms/start/cms\";\n\nimport blocks from \"./server/cms/blocks.gen\";\nimport sectionsGen from \"./server/cms/sections.gen\";\nimport meta from \"./server/cms/meta.gen.json\";\n\ncreateSiteSetup({\n  sections: import.meta.glob(\"./sections/**/*.tsx\", { eager: true }),\n  blocks,\n  meta: () =\u003e meta,\n  productionOrigins: [\"https://my-store.com\"],\n});\n\napplySectionConventions(sectionsGen);\n```\n\n### `src/worker-entry.ts`\n\n```ts\nimport \"./setup\";   // MUST be first\n\nimport { createDecoWorkerEntry } from \"@decocms/start/sdk/workerEntry\";\nimport {\n  handleMeta,\n  handleDecofile,\n  handleRender,\n  handleInvoke,\n} from \"@decocms/start/admin\";\nimport serverEntry from \"./server\";\n\nexport default createDecoWorkerEntry(serverEntry, {\n  admin: { handleMeta, handleDecofile, handleRender, handleInvoke },\n});\n```\n\n### `src/routes/$.tsx`\n\n```tsx\nimport { createFileRoute } from \"@tanstack/react-router\";\nimport { cmsRouteConfig } from \"@decocms/start/routes\";\n\nexport const Route = createFileRoute(\"/$\")(\n  cmsRouteConfig({ siteName: \"my-store\" }),\n);\n```\n\nThat is the entire skeleton. `npm install`, `npm run dev`, point `admin.deco.cx` at it, and you have a working CMS-driven site.\n\nFor commerce integrations (VTEX, Shopify) see [`@decocms/apps`](https://www.npmjs.com/package/@decocms/apps).\n\n---\n\n## Migrating from Fresh / Preact / Deno\n\n`@decocms/start` ships an Agent Skill that handles the migration for you. It works with Claude Code, Cursor, Codex, and any tool that supports skills.\n\n```bash\nnpx skills add decocms/deco-start\n```\n\nThen, in your editor, point at your Fresh storefront and prompt:\n\n\u003e migrate this project to TanStack Start\n\nThe skill runs the migration script, walks you through `MIGRATION_REPORT.md`, fixes typecheck/build errors interactively, and shows the diff before committing.\n\n### Or run the script directly\n\n```bash\n# from inside the v1 storefront directory\nnpx -p @decocms/start deco-migrate\n```\n\nThe script runs seven phases (analyze → scaffold → transform → cleanup → report → verify → bootstrap), produces `MIGRATION_REPORT.md` with manual TODOs, and gets you to \"compiles clean, builds clean\".\n\nFull migration playbook: [docs.deco.cx/v2/en/migration/overview](https://docs.deco.cx/v2/en/migration/overview).\n\n---\n\n## Documentation\n\nThe full v2 docs live at **[docs.deco.cx/v2](https://docs.deco.cx/v2/en/getting-started/overview)**:\n\n- [Getting started](https://docs.deco.cx/v2/en/getting-started/overview) — install paths, project structure, stack overview.\n- [Concepts](https://docs.deco.cx/v2/en/concepts/sections) — sections, loaders, blocks, routes, deferred rendering.\n- [Framework reference](https://docs.deco.cx/v2/en/framework/overview) — every export of `@decocms/start`, page by page.\n- [Migration](https://docs.deco.cx/v2/en/migration/overview) — v1 → v2 playbook + script + skill.\n- [Case studies](https://docs.deco.cx/v2/en/case-studies/overview) — three production stores end-to-end.\n\n---\n\n## Peer dependencies\n\n```json\n{\n  \"@tanstack/react-start\": \"\u003e=1.0.0\",\n  \"@tanstack/store\": \"\u003e=0.7.0\",\n  \"@tanstack/react-query\": \"\u003e=5.0.0\",\n  \"react\": \"^19.0.0\",\n  \"react-dom\": \"^19.0.0\",\n  \"vite\": \"\u003e=6.0.0\"\n}\n```\n\nOpenTelemetry is optional but recommended: `@microlabs/otel-cf-workers \u003e=1.0.0-rc.0`, `@opentelemetry/api \u003e=1.9.0`.\n\n---\n\n## Development\n\n```bash\nnpm run typecheck   # tsc --noEmit\nnpm run lint        # biome check\nnpm run check       # typecheck + lint + unused exports\n```\n\nThis is a library — there is no dev server here. Consumer storefronts run their own `vite dev`.\n\nContributing? See `CLAUDE.md` for the architectural decisions, and `MIGRATION_TOOLING_PLAN.md` for the append-only history of the migration tooling.\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecocms%2Fdeco-start","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdecocms%2Fdeco-start","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecocms%2Fdeco-start/lists"}