{"id":49255256,"url":"https://github.com/asteby/metacore-sdk","last_synced_at":"2026-06-12T05:01:43.330Z","repository":{"id":351920750,"uuid":"1211998131","full_name":"asteby/metacore-sdk","owner":"asteby","description":"Official SDK to build metacore addons — Go CLI, TypeScript SDK, React runtime, and 30+ examples","archived":false,"fork":false,"pushed_at":"2026-06-06T21:54:49.000Z","size":2828,"stargazers_count":2,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T23:19:43.495Z","etag":null,"topics":["create-app","fullstack","golang","metacore","monorepo","react","starter-kit","vite"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asteby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-04-16T00:55:25.000Z","updated_at":"2026-06-06T21:52:52.000Z","dependencies_parsed_at":"2026-06-03T07:05:05.107Z","dependency_job_id":null,"html_url":"https://github.com/asteby/metacore-sdk","commit_stats":null,"previous_names":["asteby/metacore-sdk"],"tags_count":241,"template":false,"template_full_name":null,"purl":"pkg:github/asteby/metacore-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asteby%2Fmetacore-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asteby%2Fmetacore-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asteby%2Fmetacore-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asteby%2Fmetacore-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asteby","download_url":"https://codeload.github.com/asteby/metacore-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asteby%2Fmetacore-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34229624,"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-06-12T02:00:06.859Z","response_time":109,"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":["create-app","fullstack","golang","metacore","monorepo","react","starter-kit","vite"],"created_at":"2026-04-25T03:00:48.180Z","updated_at":"2026-06-12T05:01:43.312Z","avatar_url":"https://github.com/asteby.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/metacore.svg\" width=\"120\" alt=\"Metacore\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eMetacore SDK\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eDeclarative addons. Zero-glue UI. Native performance.\u003c/strong\u003e\u003cbr /\u003e\n  Declare a model in \u003ccode\u003emanifest.json\u003c/code\u003e. The kernel materializes the table, endpoints and metadata.\u003cbr /\u003e\n  The SDK renders the CRUD UI. One bundle, every host.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@asteby/metacore-sdk\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@asteby/metacore-sdk?label=%40asteby%2Fmetacore-sdk\u0026color=14b8a6\" alt=\"npm version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache--2.0-blue.svg\" alt=\"License: Apache-2.0\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/asteby/metacore-sdk/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/asteby/metacore-sdk/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/changesets/changesets\"\u003e\u003cimg src=\"https://img.shields.io/badge/maintained%20with-changesets-176de3.svg\" alt=\"maintained with changesets\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://pkg.go.dev/github.com/asteby/metacore-sdk\"\u003e\u003cimg src=\"https://pkg.go.dev/badge/github.com/asteby/metacore-sdk.svg\" alt=\"Go Reference\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e 📚 **Documentation:** Full docs live at **[asteby.github.io/metacore](https://asteby.github.io/metacore/)**. The `docs/` folder in this repo is kept for offline reference only.\n\n---\n\n## Table of contents\n\n- [What is Metacore](#what-is-metacore)\n- [Why Metacore](#why-metacore)\n- [Quickstart](#quickstart)\n- [Packages](#packages)\n- [Architecture](#architecture)\n- [Documentation](#documentation)\n- [Repository layout](#repository-layout)\n- [Contributing](#contributing)\n- [Release process](#release-process)\n- [Related repositories](#related-repositories)\n- [License](#license)\n\n## What is Metacore\n\n**Metacore** is a declarative framework for extending business applications. You describe your addon with a single `manifest.json` — tables, UI contributions, webhooks, LLM tools, sandboxed permissions — and the kernel materializes it across every host that speaks Metacore.\n\n**Dynamic CRUD without the boilerplate.** Declare `models[]` in your manifest and the kernel auto-generates the database schema, REST endpoints, metadata documents and permission gates. The SDK's `\u003cDynamicTable model=\"...\" /\u003e` consumes that metadata and renders a full CRUD surface — sortable, filterable, paginated, with create/edit dialogs and custom action modals. You write zero rendering code. The same manifest powers any host application that speaks Metacore. See [`docs/dynamic-ui.md`](./docs/dynamic-ui.md) for the full UI contract.\n\nThe kernel runs sandboxed WASM backends, enforces capability scopes, manages tenant isolation, and exposes a typed bridge to React frontends. Host applications embed the kernel as a Go module and consume the SDK packages from npm. One bundle, every host.\n\n**This repository** is the public, open-source SDK that makes building, distributing and consuming Metacore addons possible:\n\n- The `metacore` Go CLI for scaffolding, validating, signing and packaging addons.\n- A monorepo of 20 npm packages under the `@asteby/*` scope that hosts and addons share — from the federated runtime to the auth kit to the design tokens.\n- Reference examples and the canonical `manifest.json` specification.\n\nThe kernel itself is private and hosted in [`asteby/metacore-kernel`](https://github.com/asteby/metacore-kernel).\n\n## Why Metacore\n\nBuilding a CRUD feature in a typical SaaS stack means writing — and maintaining — a SQL migration, a model class, a controller, a list endpoint, a detail endpoint, a create endpoint, an update endpoint, a delete endpoint, a list page with search/sort/pagination, an edit form, validation, permission middleware, and translations for every label. Per feature.\n\nWith Metacore:\n\n| You write | What is no longer your problem |\n|---|---|\n| 1 manifest entry per model (~15 lines of JSON) | The migration, the model, all four CRUD endpoints, the metadata document, the permission middleware. |\n| 1 line of TSX (`\u003cDynamicTable model=\"…\" /\u003e`) | The list view, the toolbar, filter chips, sort indicators, pagination, the edit modal, the delete confirmation, the bulk-actions bar, URL state sync, capability-gated buttons. |\n| Optional: action handlers (webhook or WASM) | Action routing, modal dispatching, form validation, confirm dialogs, error toasts. |\n\nThe cost: addons live inside the manifest's contract. When you need shapes the manifest doesn't model (multi-table joins, custom RPC, optimistic UIs), drop down to `@asteby/metacore-ui` primitives — the SDK is composable, not all-or-nothing. See [`docs/dynamic-ui.md`](./docs/dynamic-ui.md#what-you-cant-do-yet) for the honest list of limitations.\n\n## Quickstart\n\n### Three commands → working CRUD\n\n```bash\ngo install github.com/asteby/metacore-sdk/cli@latest   # 1. install the CLI\nmetacore init tickets \u0026\u0026 cd tickets                    # 2. scaffold an addon\nmetacore validate \u0026\u0026 metacore build --strict           # 3. validate + bundle\n```\n\nEdit `manifest.json` to declare your model, install the bundle in a host, and render `\u003cDynamicTable model=\"tickets\" /\u003e` in the host frontend. That's the full path. Full walkthrough — manifest, migrations, custom actions, signing, marketplace upload — in [`docs/quickstart.md`](./docs/quickstart.md).\n\n### Build a host app (Vite + React)\n\nScaffold a Vite + React host that consumes the SDK:\n\n```bash\nnpm create @asteby/metacore-app my-app -- --example fullstack-starter\ncd my-app\npnpm dev\n```\n\n`--example fullstack-starter` clones the canonical full-stack reference (Vite + React frontend + Go host). Omit it to scaffold from the bundled local template instead. The scaffolder wires `@asteby/metacore-starter-config`, `@asteby/metacore-theme`, `@asteby/metacore-ui`, auth, i18n and the runtime in one step. See [`docs/CONSUMER_GUIDE.md`](./docs/CONSUMER_GUIDE.md) for the full integration guide.\n\n## Packages\n\nAll published as `@asteby/metacore-*` on npm under Apache-2.0. Versions reflect the state at time of writing — see [npm](https://www.npmjs.com/org/asteby) or each package's `CHANGELOG.md` for current.\n\n| Package | Description | Stability |\n|---|---|---|\n| [`@asteby/metacore-sdk`](./packages/sdk) | Frontend SDK — federated addon loader, slot registry, typed manifest, API client. | stable |\n| [`@asteby/metacore-runtime-react`](./packages/runtime-react) | React runtime — renders addon contributions (DynamicTable, DynamicForm, ActionDispatcher, slots). | stable |\n| [`@asteby/metacore-ui`](./packages/ui) | Headless + styled UI kit (data-table, layout shell, command menu, dialogs, shadcn primitives). | beta |\n| [`@asteby/metacore-theme`](./packages/theme) | Design tokens, fonts, Tailwind v4 preset (oklch palette, dark mode). | beta |\n| [`@asteby/metacore-auth`](./packages/auth) | Auth kit — Zustand store, API client factory, TanStack Router guard, brand-less pages. | stable |\n| [`@asteby/metacore-i18n`](./packages/i18n) | i18next factory, base ES/EN bundles, language switcher, RTL provider. | stable |\n| [`@asteby/metacore-lib`](./packages/lib) | Pure utilities — date, currency, number formatting, error handling. | beta |\n| [`@asteby/metacore-tools`](./packages/tools) | TypeScript client for the kernel Tools runtime — execution, registry, validation. | alpha |\n| [`@asteby/metacore-websocket`](./packages/websocket) | WebSocket provider — auto-reconnect, typed messages, channel subscriptions. | beta |\n| [`@asteby/metacore-notifications`](./packages/notifications) | Notifications dropdown, app badge, real-time WebSocket updates. | stable |\n| [`@asteby/metacore-webhooks`](./packages/webhooks) | Webhooks management UI — list, create, logs, test/replay, signing secrets. | stable |\n| [`@asteby/metacore-pwa`](./packages/pwa) | PWA helpers — Vite plugin wrapper, install/update prompts, push, offline. | beta |\n| [`@asteby/metacore-app-providers`](./packages/app-providers) | Generic providers — direction, font, layout, search palette. | beta |\n| [`@asteby/metacore-starter-config`](./packages/starter-config) | Shared Vite, TypeScript, Tailwind 4 and ESLint presets. | beta |\n| [`@asteby/metacore-starter-core`](./packages/starter-core) | Starter scaffolding — providers, hooks, UI primitives. | beta |\n| [`@asteby/create-metacore-app`](./packages/create-metacore-app) | `npm create` scaffolder for new Metacore Vite + React apps. | beta |\n| [`@asteby/metacore-marketplace`](./packages/marketplace) | Marketplace SDK — hub/ops clients, React Query hooks, headless catalog/install UI. | alpha |\n| [`@asteby/metacore-billing`](./packages/billing) | Billing UI primitives shared across hosts. | alpha |\n| [`@asteby/metacore-starter-monaco`](./packages/starter-monaco) | Monaco editor preset for in-app code/manifest editing. | alpha |\n| [`create-metacore-addon`](./packages/create-addon) | `npm create` scaffolder for new Metacore addons. | alpha |\n\n\u003e Stability legend: `alpha` = pre-1.0, breaking changes likely; `beta` = pre-1.0 but stabilizing; `stable` = 1.0+ with semver discipline.\n\n## Architecture\n\n```\n   ┌─────────────────────────────────────────────────────────────────────┐\n   │                        Addon (your code)                            │\n   │             manifest.json — declarative contract                    │\n   │     models[] · contributions{} · capabilities[] · rbac{} · …        │\n   │            + migrations/ · frontend/ · WASM backend                 │\n   └─────────────────────────────┬───────────────────────────────────────┘\n                                 │\n                                 ▼\n   ┌─────────────────────────────────────────────────────────────────────┐\n   │                  metacore-sdk (this repo, public)                   │\n   │   CLI ─ Go pkg ─ @asteby/metacore-{sdk, runtime-react, ui, …}       │\n   └─────────────────────────────┬───────────────────────────────────────┘\n                                 │\n                                 ▼\n   ┌─────────────────────────────────────────────────────────────────────┐\n   │                  metacore-kernel (Go, private)                      │\n   │     manifest parser · AutoMigrate · WASM runtime · capability       │\n   │      enforcer · WebSocket hub · installer · lifecycle hooks         │\n   └────────────┬────────────────────────────────────────────────────────┘\n                │\n                │  REST + WebSocket\n                │\n                ▼\n   ┌──────────────────────────────────────────┐         ┌──────────────┐\n   │  /metadata/table/\u003cmodel\u003e     ◀──── caches│         │              │\n   │  /metadata/modal/\u003cmodel\u003e     ◀──── caches│         │  Host apps   │\n   │  /data/\u003cmodel\u003e            (CRUD list/CRUD)         │              │\n   │  /data/\u003cmodel\u003e/\u003cid\u003e/action/\u003ckey\u003e          │  ◀────▶│  Any app     │\n   │  /options/\u003cendpoint\u003e          (FK pickers)│         │  that embeds │\n   └──────────────────────────────────────────┘         │  the kernel  │\n                │                                       │              │\n                │                                       │              │\n                ▼                                       │              │\n   ┌──────────────────────────────────────────┐         │              │\n   │  \u003cDynamicTable model=\"tickets\" /\u003e        │  ◀──────┤              │\n   │  \u003cDynamicForm fields={…} /\u003e              │         │              │\n   │  \u003cDynamicRecordDialog /\u003e                 │         │ Hosts embed  │\n   │  \u003cActionModalDispatcher /\u003e               │         │ the kernel   │\n   │  \u003cCapabilityGate require=\"…\"\u003e            │         │ as a Go      │\n   └──────────────────────────────────────────┘         │ module and   │\n        runtime-react renders metadata into UI         │ consume      │\n                                                        │ @asteby/*    │\n                                                        │ from npm.    │\n                                                        └──────────────┘\n```\n\n- **Manifest → Kernel.** You write a manifest and (optionally) a TinyGo WASM backend. The CLI validates, signs and packages a `.tar.gz`. The kernel parses it, runs migrations under tenant isolation, loads the WASM bundle into wazero, and serves CRUD endpoints + metadata documents.\n- **Kernel → Metadata.** For every declared model the kernel exposes `/metadata/table/\u003cmodel\u003e` (columns, filters, actions), `/metadata/modal/\u003cmodel\u003e` (form schema), and `/metadata/all` (one-shot prefetch).\n- **Metadata → UI.** `\u003cDynamicTable\u003e` reads the metadata, fetches `/data/\u003cmodel\u003e` paginated, renders rows with cell-type-aware renderers, and dispatches custom actions to `\u003cActionModalDispatcher\u003e`. No code is written per feature.\n- **Kernel → Host.** Host applications embed the kernel as a Go module. Their React frontends import from `@asteby/metacore-*` to render the contributions consistently.\n\n## Manifest contract version\n\n\u003e **Canonical: Module Contract v3 (`apiVersion: \"asteby.com/v3\"`).**\n\u003e The `metacore` CLI, the generated TypeScript types (`@asteby/metacore-sdk`)\n\u003e and the bundled examples all **emit and validate v3**. This repo pins\n\u003e `metacore-kernel v0.20.0` and validates manifests with the kernel's strict\n\u003e `manifest/v3` parser. A v3 manifest declares `apiVersion`, `kind`\n\u003e (`Addon`/`Preset`/`Theme`/`ConnectorPack`), a nested `metadata{}` block, a\n\u003e `compatibility{}` block (semver kernel range), `models[]` (full column\n\u003e definitions, replacing the v2 `model_definitions[]`), `contributions{}`\n\u003e (navigation/actions/tools/subscriptions/slots), `extension_points{}`,\n\u003e `rbac{}` and top-level `settings[]`. v3 is strict — unknown fields are\n\u003e rejected and keys are SQL-style underscore.\n\u003e\n\u003e Scaffold one with `metacore init \u003ckey\u003e` or `npx create-metacore-addon`.\n\u003e The authoritative grammar (JSON schema, v2→v3 migration guide, canonical\n\u003e examples) lives in the kernel repo under `docs/spec/v3/`.\n\u003e\n\u003e **v2 compatibility.** The kernel *dual-reads* legacy v2 manifests (no\n\u003e `apiVersion`) throughout the 3.x line, so already-published v2 addons keep\n\u003e installing. New addons author v3; v2 support is removed in the 4.x kernel\n\u003e train.\n\n## Documentation\n\n| Doc | What it covers |\n|---|---|\n| [`docs/quickstart.md`](./docs/quickstart.md) | Build a CRUD addon in 5 minutes — declare a model, render a table. |\n| [`docs/dynamic-ui.md`](./docs/dynamic-ui.md) | The Dynamic UI framework — `\u003cDynamicTable\u003e`, `\u003cDynamicForm\u003e`, `\u003cActionModalDispatcher\u003e`, capability gates. |\n| [`docs/addon-cookbook.md`](./docs/addon-cookbook.md) | Recipes — foreign keys, soft delete, custom actions, events, federation. |\n| [`docs/manifest-spec.md`](./docs/manifest-spec.md) | Every field of `manifest.json`. The CLI emits/validates Module Contract **v3** (`apiVersion: \"asteby.com/v3\"`); the page links the authoritative v3 schema in the kernel and retains the legacy v2 field reference (the kernel dual-reads v2). |\n| [`docs/capabilities.md`](./docs/capabilities.md) | Declaring scoped permissions safely. |\n| [`docs/wasm-abi.md`](./docs/wasm-abi.md) | Writing a sandboxed WASM backend (TinyGo ABI). |\n| [`docs/CONSUMER_GUIDE.md`](./docs/CONSUMER_GUIDE.md) | Apps consuming the npm packages — install, Vite, Tailwind, deploy, Renovate. |\n| [`docs/addon-publishing.md`](./docs/addon-publishing.md) | Signing, uploading and the marketplace review flow. |\n| [`docs/PUBLISHING.md`](./docs/PUBLISHING.md) | Releasing the SDK packages — Changesets, Release PR, npm publish. |\n| [`docs/internal-setup.md`](./docs/internal-setup.md) | Local setup for SDK contributors. |\n\n## Repository layout\n\n```\nmetacore-sdk/\n├── cli/          # `metacore` Go CLI — init, validate, build, sign, compile-wasm\n│                 #   (manifest types + signing come from the metacore-kernel module)\n├── packages/     # pnpm workspace — 20 npm packages under @asteby/metacore-*\n├── examples/     # reference addons (fiscal-mx, tickets, hello-wasm)\n├── templates/    # scaffold templates embedded by the CLI\n├── docs/         # public documentation served from this folder\n└── .changeset/   # version + changelog state for the npm release pipeline\n```\n\n## Contributing\n\nIssues, pull requests and design RFCs are welcome. Read [`CONTRIBUTING.md`](./CONTRIBUTING.md) and [`SECURITY.md`](./SECURITY.md) before opening a PR — security reports go to `security@asteby.com`.\n\n**Any PR that touches `packages/*` must include a Changeset.** From the repo root:\n\n```bash\npnpm changeset\n```\n\nPick the affected packages, the bump level (`patch` / `minor` / `major`), and write a one-line summary aimed at consumers. Commit the generated `.changeset/*.md` alongside your code. Reviewers expect both — see the [Changesets docs](https://github.com/changesets/changesets) for the full model.\n\nFor local setup, see [`docs/internal-setup.md`](./docs/internal-setup.md).\n\n## Release process\n\nReleases are fully automated through [Changesets](https://github.com/changesets/changesets) + GitHub Actions:\n\n1. **Author:** open a PR with your code change plus a `.changeset/*.md` entry generated by `pnpm changeset`.\n2. **Merge to `main`:** the [`Release npm packages`](./.github/workflows/release-npm.yml) workflow runs.\n3. **Version PR:** if there are unreleased changesets, the workflow opens (or updates) a `chore(release): version packages` PR. Its diff bumps `package.json` versions, regenerates `CHANGELOG.md`, and consumes the changesets.\n4. **Publish:** merging the version PR runs `changeset publish`, building the affected packages and pushing them to npm under the `@asteby` scope.\n5. **Propagate:** consumer host applications receive a Renovate PR within minutes — patch and minor bumps auto-merge, majors await human review.\n\nThe workflow uses `NPM_TOKEN` (a Granular Access Token with **Bypass 2FA** enabled, scoped to publish on `@asteby`). Linked packages — `@asteby/metacore-ui` and `@asteby/metacore-theme` — version together; the rest version independently via Changesets.\n\nFull details and troubleshooting in [`docs/PUBLISHING.md`](./docs/PUBLISHING.md).\n\n## Related repositories\n\n**Framework** (`asteby/`):\n\n- [`metacore-sdk`](https://github.com/asteby/metacore-sdk) — this repo (public).\n- [`metacore-kernel`](https://github.com/asteby/metacore-kernel) — runtime kernel (private).\n\nHosts can run any compatible marketplace; configure the URL via the\n`VITE_HUB_URL` environment variable on the consumer app (defaults to a\nplaceholder — see `examples/fullstack-starter/frontend/.env.example`).\n\n## License\n\nApache License 2.0. Copyright 2026 Asteby, Inc. See [`LICENSE`](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasteby%2Fmetacore-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasteby%2Fmetacore-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasteby%2Fmetacore-sdk/lists"}