https://github.com/asteby/metacore-sdk

Official SDK to build metacore addons — Go CLI, TypeScript SDK, React runtime, and 30+ examples
https://github.com/asteby/metacore-sdk
create-app fullstack golang metacore monorepo react starter-kit vite
Last synced: 14 days ago
JSON representation
Official SDK to build metacore addons — Go CLI, TypeScript SDK, React runtime, and 30+ examples
Host: GitHub
URL: https://github.com/asteby/metacore-sdk
Owner: asteby
License: apache-2.0
Created: 2026-04-16T00:55:25.000Z (2 months ago)
Default Branch: main
Last Pushed: 2026-06-06T21:54:49.000Z (19 days ago)
Last Synced: 2026-06-06T23:19:43.495Z (19 days ago)
Topics: create-app, fullstack, golang, metacore, monorepo, react, starter-kit, vite
Language: TypeScript
Size: 2.7 MB
Stars: 2
Watchers: 0
Forks: 0
Open Issues: 4
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project

README

          


  



Metacore SDK




  Declarative addons. Zero-glue UI. Native performance.


  Declare a model in manifest.json. The kernel materializes the table, endpoints and metadata.


  The SDK renders the CRUD UI. One bundle, every host.





  

  

  

  

  



> 📚 **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.

---

## Table of contents

- [What is Metacore](#what-is-metacore)

- [Why Metacore](#why-metacore)

- [Quickstart](#quickstart)

- [Packages](#packages)

- [Architecture](#architecture)

- [Documentation](#documentation)

- [Repository layout](#repository-layout)

- [Contributing](#contributing)

- [Release process](#release-process)

- [Related repositories](#related-repositories)

- [License](#license)

## What is Metacore

**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.

**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 `` 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.

The 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.

**This repository** is the public, open-source SDK that makes building, distributing and consuming Metacore addons possible:

- The `metacore` Go CLI for scaffolding, validating, signing and packaging addons.

- 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.

- Reference examples and the canonical `manifest.json` specification.

The kernel itself is private and hosted in [`asteby/metacore-kernel`](https://github.com/asteby/metacore-kernel).

## Why Metacore

Building 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.

With Metacore:

| You write | What is no longer your problem |

|---|---|

| 1 manifest entry per model (~15 lines of JSON) | The migration, the model, all four CRUD endpoints, the metadata document, the permission middleware. |

| 1 line of TSX (``) | 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. |

| Optional: action handlers (webhook or WASM) | Action routing, modal dispatching, form validation, confirm dialogs, error toasts. |

The 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.

## Quickstart

### Three commands → working CRUD

```bash

go install github.com/asteby/metacore-sdk/cli@latest   # 1. install the CLI

metacore init tickets && cd tickets                    # 2. scaffold an addon

metacore validate && metacore build --strict           # 3. validate + bundle

```

Edit `manifest.json` to declare your model, install the bundle in a host, and render `` 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).

### Build a host app (Vite + React)

Scaffold a Vite + React host that consumes the SDK:

```bash

npm create @asteby/metacore-app my-app -- --example fullstack-starter

cd my-app

pnpm dev

```

`--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.

## Packages

All 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.

| Package | Description | Stability |

|---|---|---|

| [`@asteby/metacore-sdk`](./packages/sdk) | Frontend SDK — federated addon loader, slot registry, typed manifest, API client. | stable |

| [`@asteby/metacore-runtime-react`](./packages/runtime-react) | React runtime — renders addon contributions (DynamicTable, DynamicForm, ActionDispatcher, slots). | stable |

| [`@asteby/metacore-ui`](./packages/ui) | Headless + styled UI kit (data-table, layout shell, command menu, dialogs, shadcn primitives). | beta |

| [`@asteby/metacore-theme`](./packages/theme) | Design tokens, fonts, Tailwind v4 preset (oklch palette, dark mode). | beta |

| [`@asteby/metacore-auth`](./packages/auth) | Auth kit — Zustand store, API client factory, TanStack Router guard, brand-less pages. | stable |

| [`@asteby/metacore-i18n`](./packages/i18n) | i18next factory, base ES/EN bundles, language switcher, RTL provider. | stable |

| [`@asteby/metacore-lib`](./packages/lib) | Pure utilities — date, currency, number formatting, error handling. | beta |

| [`@asteby/metacore-tools`](./packages/tools) | TypeScript client for the kernel Tools runtime — execution, registry, validation. | alpha |

| [`@asteby/metacore-websocket`](./packages/websocket) | WebSocket provider — auto-reconnect, typed messages, channel subscriptions. | beta |

| [`@asteby/metacore-notifications`](./packages/notifications) | Notifications dropdown, app badge, real-time WebSocket updates. | stable |

| [`@asteby/metacore-webhooks`](./packages/webhooks) | Webhooks management UI — list, create, logs, test/replay, signing secrets. | stable |

| [`@asteby/metacore-pwa`](./packages/pwa) | PWA helpers — Vite plugin wrapper, install/update prompts, push, offline. | beta |

| [`@asteby/metacore-app-providers`](./packages/app-providers) | Generic providers — direction, font, layout, search palette. | beta |

| [`@asteby/metacore-starter-config`](./packages/starter-config) | Shared Vite, TypeScript, Tailwind 4 and ESLint presets. | beta |

| [`@asteby/metacore-starter-core`](./packages/starter-core) | Starter scaffolding — providers, hooks, UI primitives. | beta |

| [`@asteby/create-metacore-app`](./packages/create-metacore-app) | `npm create` scaffolder for new Metacore Vite + React apps. | beta |

| [`@asteby/metacore-marketplace`](./packages/marketplace) | Marketplace SDK — hub/ops clients, React Query hooks, headless catalog/install UI. | alpha |

| [`@asteby/metacore-billing`](./packages/billing) | Billing UI primitives shared across hosts. | alpha |

| [`@asteby/metacore-starter-monaco`](./packages/starter-monaco) | Monaco editor preset for in-app code/manifest editing. | alpha |

| [`create-metacore-addon`](./packages/create-addon) | `npm create` scaffolder for new Metacore addons. | alpha |

> Stability legend: `alpha` = pre-1.0, breaking changes likely; `beta` = pre-1.0 but stabilizing; `stable` = 1.0+ with semver discipline.

## Architecture

```

   ┌─────────────────────────────────────────────────────────────────────┐

   │                        Addon (your code)                            │

   │             manifest.json — declarative contract                    │

   │     models[] · contributions{} · capabilities[] · rbac{} · …        │

   │            + migrations/ · frontend/ · WASM backend                 │

   └─────────────────────────────┬───────────────────────────────────────┘

                                 │

                                 ▼

   ┌─────────────────────────────────────────────────────────────────────┐

   │                  metacore-sdk (this repo, public)                   │

   │   CLI ─ Go pkg ─ @asteby/metacore-{sdk, runtime-react, ui, …}       │

   └─────────────────────────────┬───────────────────────────────────────┘

                                 │

                                 ▼

   ┌─────────────────────────────────────────────────────────────────────┐

   │                  metacore-kernel (Go, private)                      │

   │     manifest parser · AutoMigrate · WASM runtime · capability       │

   │      enforcer · WebSocket hub · installer · lifecycle hooks         │

   └────────────┬────────────────────────────────────────────────────────┘

                │

                │  REST + WebSocket

                │

                ▼

   ┌──────────────────────────────────────────┐         ┌──────────────┐

   │  /metadata/table/     ◀──── caches│         │              │

   │  /metadata/modal/     ◀──── caches│         │  Host apps   │

   │  /data/            (CRUD list/CRUD)         │              │

   │  /data///action/          │  ◀────▶│  Any app     │

   │  /options/          (FK pickers)│         │  that embeds │

   └──────────────────────────────────────────┘         │  the kernel  │

                │                                       │              │

                │                                       │              │

                ▼                                       │              │

   ┌──────────────────────────────────────────┐         │              │

   │          │  ◀──────┤              │

   │                │         │              │

   │                   │         │ Hosts embed  │

   │                 │         │ the kernel   │

   │              │         │ as a Go      │

   └──────────────────────────────────────────┘         │ module and   │

        runtime-react renders metadata into UI         │ consume      │

                                                        │ @asteby/*    │

                                                        │ from npm.    │

                                                        └──────────────┘

```

- **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.

- **Kernel → Metadata.** For every declared model the kernel exposes `/metadata/table/` (columns, filters, actions), `/metadata/modal/` (form schema), and `/metadata/all` (one-shot prefetch).

- **Metadata → UI.** `` reads the metadata, fetches `/data/` paginated, renders rows with cell-type-aware renderers, and dispatches custom actions to ``. No code is written per feature.

- **Kernel → Host.** Host applications embed the kernel as a Go module. Their React frontends import from `@asteby/metacore-*` to render the contributions consistently.

## Manifest contract version

> **Canonical: Module Contract v3 (`apiVersion: "asteby.com/v3"`).**

> The `metacore` CLI, the generated TypeScript types (`@asteby/metacore-sdk`)

> and the bundled examples all **emit and validate v3**. This repo pins

> `metacore-kernel v0.20.0` and validates manifests with the kernel's strict

> `manifest/v3` parser. A v3 manifest declares `apiVersion`, `kind`

> (`Addon`/`Preset`/`Theme`/`ConnectorPack`), a nested `metadata{}` block, a

> `compatibility{}` block (semver kernel range), `models[]` (full column

> definitions, replacing the v2 `model_definitions[]`), `contributions{}`

> (navigation/actions/tools/subscriptions/slots), `extension_points{}`,

> `rbac{}` and top-level `settings[]`. v3 is strict — unknown fields are

> rejected and keys are SQL-style underscore.

>

> Scaffold one with `metacore init ` or `npx create-metacore-addon`.

> The authoritative grammar (JSON schema, v2→v3 migration guide, canonical

> examples) lives in the kernel repo under `docs/spec/v3/`.

>

> **v2 compatibility.** The kernel *dual-reads* legacy v2 manifests (no

> `apiVersion`) throughout the 3.x line, so already-published v2 addons keep

> installing. New addons author v3; v2 support is removed in the 4.x kernel

> train.

## Documentation

| Doc | What it covers |

|---|---|

| [`docs/quickstart.md`](./docs/quickstart.md) | Build a CRUD addon in 5 minutes — declare a model, render a table. |

| [`docs/dynamic-ui.md`](./docs/dynamic-ui.md) | The Dynamic UI framework — ``, ``, ``, capability gates. |

| [`docs/addon-cookbook.md`](./docs/addon-cookbook.md) | Recipes — foreign keys, soft delete, custom actions, events, federation. |

| [`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). |

| [`docs/capabilities.md`](./docs/capabilities.md) | Declaring scoped permissions safely. |

| [`docs/wasm-abi.md`](./docs/wasm-abi.md) | Writing a sandboxed WASM backend (TinyGo ABI). |

| [`docs/CONSUMER_GUIDE.md`](./docs/CONSUMER_GUIDE.md) | Apps consuming the npm packages — install, Vite, Tailwind, deploy, Renovate. |

| [`docs/addon-publishing.md`](./docs/addon-publishing.md) | Signing, uploading and the marketplace review flow. |

| [`docs/PUBLISHING.md`](./docs/PUBLISHING.md) | Releasing the SDK packages — Changesets, Release PR, npm publish. |

| [`docs/internal-setup.md`](./docs/internal-setup.md) | Local setup for SDK contributors. |

## Repository layout

```

metacore-sdk/

├── cli/          # `metacore` Go CLI — init, validate, build, sign, compile-wasm

│                 #   (manifest types + signing come from the metacore-kernel module)

├── packages/     # pnpm workspace — 20 npm packages under @asteby/metacore-*

├── examples/     # reference addons (fiscal-mx, tickets, hello-wasm)

├── templates/    # scaffold templates embedded by the CLI

├── docs/         # public documentation served from this folder

└── .changeset/   # version + changelog state for the npm release pipeline

```

## Contributing

Issues, 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`.

**Any PR that touches `packages/*` must include a Changeset.** From the repo root:

```bash

pnpm changeset

```

Pick 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.

For local setup, see [`docs/internal-setup.md`](./docs/internal-setup.md).

## Release process

Releases are fully automated through [Changesets](https://github.com/changesets/changesets) + GitHub Actions:

1. **Author:** open a PR with your code change plus a `.changeset/*.md` entry generated by `pnpm changeset`.

2. **Merge to `main`:** the [`Release npm packages`](./.github/workflows/release-npm.yml) workflow runs.

3. **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.

4. **Publish:** merging the version PR runs `changeset publish`, building the affected packages and pushing them to npm under the `@asteby` scope.

5. **Propagate:** consumer host applications receive a Renovate PR within minutes — patch and minor bumps auto-merge, majors await human review.

The 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.

Full details and troubleshooting in [`docs/PUBLISHING.md`](./docs/PUBLISHING.md).

## Related repositories

**Framework** (`asteby/`):

- [`metacore-sdk`](https://github.com/asteby/metacore-sdk) — this repo (public).

- [`metacore-kernel`](https://github.com/asteby/metacore-kernel) — runtime kernel (private).

Hosts can run any compatible marketplace; configure the URL via the

`VITE_HUB_URL` environment variable on the consumer app (defaults to a

placeholder — see `examples/fullstack-starter/frontend/.env.example`).

## License

Apache License 2.0. Copyright 2026 Asteby, Inc. See [`LICENSE`](./LICENSE).
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/asteby/metacore-sdk

Awesome Lists containing this project

README

Metacore SDK
