@middag-io/react

Shared React UI library for the MIDDAG ecosystem. Consumed by Moodle (local_middag) and WordPress host plugins via Inertia.js.

Live Demo | Documentation

Stack

• React 19, TypeScript, Tailwind CSS v4
• Inertia.js (peer dependency — all hosts use Inertia)
• ReUI components (Radix-based)
• TanStack Table, @xyflow/react, @dnd-kit

Install

Quick start (recommended)

npx create-middag-ui

The wizard detects your host platform (Moodle/WordPress), configures authentication, and scaffolds a ui/ directory with a working build.

Manual install

npm public (no auth needed):

npm install @middag-io/react react react-dom @inertiajs/react @inertiajs/core

GitHub Packages (includes TypeScript source for IDE navigation):

# Add to global ~/.npmrc
echo "@middag-io:registry=https://npm.pkg.github.com" >> ~/.npmrc
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> ~/.npmrc

npm install @middag-io/react react react-dom @inertiajs/react @inertiajs/core

Create a token at github.com/settings/tokens with read:packages scope. See Authentication for details.

Distribution

@middag-io/react is the complete rendering engine — every block, shell, layout, contract and registry you need to build plugins. Two ways to install it:

• npm (public, no auth): compiled ESM bundle + type declarations + declaration maps.
• GitHub Packages (auth): adds the TypeScript src/ for IDE "go to definition". Requires a read:packages token (see above).

MIDDAG also offers a commercial Pro tier (@middag-io/react-pro) — additional blocks, an application shell and extra themes, used for internal products and consulting. Not needed to build with this library.

Usage

import { ContractPage, registerDefaults } from '@middag-io/react';
import type { PageContract } from '@middag-io/react';

// Register core shells, layouts, and the standard Community blocks
registerDefaults();

// Render a contract-driven page
<ContractPage contract={myContract} />

Selective registration (IIFE consumers)

WordPress and other IIFE consumers should import only the blocks they need to avoid bundling heavy dependencies (@xyflow/react, @dnd-kit, zod, react-hook-form) via inlineDynamicImports:

import {
  registerShell, registerLayout, registerBlock,
  BasicShell, StackLayout, SidebarLayout, DashboardLayout,
  DenseTableBlock, MetricCardBlock, EmptyStateBlock,
} from '@middag-io/react';

registerShell('product', BasicShell);
registerLayout('stack', StackLayout);
registerLayout('sidebar', SidebarLayout);
registerLayout('dashboard', DashboardLayout);
registerBlock('dense_table', DenseTableBlock);
registerBlock('metric_card', MetricCardBlock);
registerBlock('empty_state', EmptyStateBlock);

Lazy block loading

Blocks can defer data loading until they mount (useful for tabbed pages):

// PHP sends block with empty data + lazyProp metadata:
{
  type: 'dense_table',
  key: 'invoices',
  data: {},
  meta: { lazyProp: 'invoices' }
}

// PHP also sends a top-level Inertia prop (initially null):
// 'invoices' => null

// When the block mounts, it auto-fetches via router.reload({ only: ['invoices'] })
// Radix Tabs unmounts inactive tabs, so lazy blocks only fetch when their tab activates

ReUI components

Consumers can import ReUI primitives for custom components:

import { Tabs, TabsList, TabsTrigger, TabsContent } from '@middag-io/react/reui/tabs';
import { Button } from '@middag-io/react/reui/button';

Custom blocks

import { registerBlock, type BlockProps } from '@middag-io/react';

function ChartBlock({ block }: BlockProps<{ labels: string[]; values: number[] }>) {
  return <div>{/* your chart */}</div>;
}

registerBlock('chart', ChartBlock);

Contract validation

import { validatePageContract } from '@middag-io/react';

const errors = validatePageContract(contractFromBackend);
if (errors) {
  console.error('Invalid contract:', errors);
}

Zod schemas are exported for consumers who want to extend validation or generate JSON Schema for PHP consumers.

i18n with host-specific resolver

import { I18nProvider } from '@middag-io/react';

// Moodle: inject Moodle string resolver
<I18nProvider asyncResolver={moodleGetStrings}>
  <App />
</I18nProvider>

// WordPress: inject WP i18n resolver
<I18nProvider asyncResolver={wpGetStrings}>
  <App />
</I18nProvider>

Architecture

src/
  app/           # ContractPage, registries (shell/layout/block), providers, LazyBlock
  base/          # Shells, layouts, blocks, hooks, theme, form, partials, registries (field/icon/cell)
  components/
    reui/        # ReUI primitives (Radix-based, source of truth)
    examples/    # ReUI component examples (synced from registry)
  contracts/     # TypeScript types (PageContract, BlockData, etc.)
  lib/           # Generic utilities and hooks
  assets/        # Fonts, lottie animations
  index.ts       # Barrel export
demo/            # Demo harness (standalone SPA — `npm run dev`)
docs/            # Guides, reference and the public JSON schemas
scripts/         # Tooling (contracts codegen, docs payload, sync, doctor)
.githooks/       # Git hooks (pre-commit, commit-msg, pre-push)

What belongs here vs host plugins

Here (@middag-io/react)	Host plugin (Moodle/WP)
Shells, layouts, blocks	Extensions with host-specific pages
ContractPage renderer	Inertia server-side adapter
Theme system	License validation (server-side)
i18n provider (generic)	i18n resolver (host-specific)
Type contracts	API endpoints, DB queries
ReUI examples (reference)	Custom components

Development

# Check environment
npm run doctor

# Demo harness -- standalone SPA, no server needed
npm run dev             # http://localhost:5173

# Typecheck
npm run typecheck

# Lint
npm run lint:fix

# Tests
npm test

# Build ESM lib
npm run build

The demo harness consumes the engine from src/ via Vite aliases (instant HMR), mocks @inertiajs/* with self-contained adapters in demo/adapters/, and renders PageContracts end to end.

ReUI component examples

Examples from the ReUI registry are synced to src/components/examples/. They serve as reference for component usage and are excluded from the published NPM package.

# Sync all examples from ReUI registry (auto-discovers new components)
npm run sync:examples

# Preview what would be synced
npm run sync:examples -- --dry-run

# Check if new examples are available (used by CI)
npm run sync:examples -- --check

A GitHub Action runs weekly (Mondays 8:00 UTC) to check for new examples and opens a PR automatically if updates are available.

Git Hooks

Configured via .githooks/ (activated by npm run prepare):

Hook	Trigger	Protection
pre-commit	git commit	Typecheck + lint on staged files
commit-msg	git commit	Enforces Conventional Commits format
pre-push	git push	Typecheck + contract drift + lib build

Versioning

release-please owns versioning: it scans Conventional Commits on main, opens a release PR (version bump + CHANGELOG.md) and, on merge, cuts the tag + GitHub release and publishes. Commit types decide the bump (0.x rule: feat/breaking = minor, fix = patch).

CLI

The package includes a CLI for bootstrapping and maintaining the UI layer in consumer projects:

Command	Description
npx create-middag-ui	Bootstrap ui/
npx @middag-io/react doctor	Validate consumer project setup (deps, configs, peer deps)
npx @middag-io/react dev	Start mock dev server from consumer project
npx @middag-io/react add-block <type>	Scaffold a new block type with component + mock factory
npx @middag-io/react upgrade	Check for updates and run codemods

Scripts

Command	Description
npm run doctor	Validate development environment
npm run dev	Demo harness (demo/)
npm run build	Build ESM lib to dist-lib/
npm run typecheck	TypeScript type check
npm run lint	ESLint check
npm run lint:fix	ESLint auto-fix
npm run format	Prettier format
npm run format:check	Prettier check
npm test	Vitest run (all tests)
npm run gen:contracts	Regenerate contract types from JSON schemas
npm run sync:examples	Sync ReUI examples from registry
npm run docs:build	Build + verify the public docs payload

Peer Dependencies

• react ^19.0.0
• react-dom ^19.0.0
• @inertiajs/react ^3.0.0
• @inertiajs/core ^3.0.0

CI/CD

Workflow	Trigger	What it does
ci.yml	Pull requests to main	Static checks + contract drift + tests/coverage + build
publish.yml	Push to main	release-please → publish to GitHub Packages + npm public → docs
notify-schemas-updated.yml	Push to main (docs/public/schemas)	Notifies downstream consumers of schema changes
sync-examples.yml	Monday 8:00 UTC / manual	Sync ReUI examples, opens PR if updates

License

Apache-2.0 OSS. The rendering engine, the standard Community blocks, shells, layouts, contracts and registries. Free to use, fork and ship. See LICENSE.

The commercial Pro tier (@middag-io/react-pro — additional blocks, an application shell, extra themes) is a separate, proprietary package distributed via GitHub Packages. It is not part of this repository and is not needed to build with this library.