mythik-react

The React rendering surface for Mythik contracts. Mount a multi-screen app via MythikApp, embed a single spec via MythikRenderer, and let validated JSON from your store become UI at runtime. The host stays small while the contract changes.

See the framework README on GitHub for the full Mythik architecture and design philosophy. This file documents what mythik-react gives you and how to use it.

What Mythik is, briefly

Mythik is an AI-first JSON-native app framework. Most of your app lives as validated JSON specs loaded at runtime from your database, not source code that must be regenerated and redeployed for every change. AI agents compose those specs from a documented vocabulary; Mythik validates the shape, references, actions, state paths, and cross-contract assumptions before the change reaches runtime. This package is the React rendering surface: it turns those same validated JSON contracts into web app screens.

Install

npm install mythik mythik-react

mythik is a peer dependency: it ships the spec types, validators, and runtime engines. mythik-react adds the React renderer on top.

What you get

• <MythikApp> — full multi-screen app shell. Reads an AppSpec (navigation, screens, theme, app-level layout) plus a SpecStore and renders the active screen, handles navigation, manages auth context, and coordinates editor sessions.

• <MythikRenderer> — single-spec renderer for embedding Mythik inside an existing React app. Useful for islands and demos where you don't need the full app shell.

• 38 built-in primitives — form fields, layout, lists, modals, charts, and more. Each primitive maps a spec type value (e.g. "button") to a React component with a strict prop schema. See ai-context-primitives.md (bundled in the mythik package) for the full catalog.

• Customization hooks — register custom primitives, expressions, and action handlers via MythikApp.onPlugins. The icon renderer is hookable via plugins.setIconRenderer.

• Auth provider re-exports — convenience surface sourced from mythik core, so your app can import everything auth-related from one place.

Minimal example

A two-screen app, all behavior described in JSON:

import { MemorySpecStore, type AppSpec, type Spec } from 'mythik';
import { MythikApp } from 'mythik-react';

const appSpec: AppSpec = {
  type: 'app',
  name: 'Demo App',
  navigation: { type: 'tabs', initialScreen: 'home' },
  screens: {
    home:    { label: 'Home' },
    profile: { label: 'Profile' },
  },
  layout: {
    root: 'app-shell',
    elements: {
      'app-shell': {
        type: 'box',
        props: { style: { minHeight: '100vh', padding: 24 } },
        children: ['outlet'],
      },
      outlet: { type: 'screen-outlet' },
    },
  },
};

const homeSpec: Spec = {
  root: 'root',
  elements: {
    root: {
      type: 'box',
      props: { style: { padding: 24 } },
      children: ['title', 'go-profile'],
    },
    title: {
      type: 'text',
      props: { content: 'Hello from Mythik', variant: 'heading' },
    },
    'go-profile': {
      type: 'button',
      props: { label: 'View profile' },
      on: { press: [{ action: 'navigateScreen', params: { screen: 'profile' } }] },
    },
  },
};

const profileSpec: Spec = {
  root: 'root',
  elements: {
    root: { type: 'text', props: { content: 'Profile screen' } },
  },
};

const specStore = new MemorySpecStore({
  home: homeSpec,
  profile: profileSpec,
});

export default function App() {
  return (
    <MythikApp
      appSpec={appSpec}
      specStore={specStore}
      apiBaseUrl="http://localhost:3010"
    />
  );
}

Replace MemorySpecStore with SupabaseSpecStore or a SqlSpecStore from mythik/server backed by SQL Server, PostgreSQL, MySQL, or SQLite. The host file does not change as the app grows from 2 screens to 200.

apiBaseUrl is the host-level base for framework-owned runtime fetches. Specs can keep URLs relative (/api/orders, /api/catalog/services) and the renderer resolves them before URL guards, auth interceptors, and fetch execution. When web auth is enabled and authDomains is omitted or empty, the exact origin of apiBaseUrl becomes the default auth target; same-host services on other ports do not inherit that token.

How the renderer works

When MythikApp mounts:

1. It loads the active spec from the SpecStore.
2. It walks the spec's element tree starting from root.
3. For each element, it instantiates the React component registered for that element's type value (built-in primitive or custom).
4. It resolves $token, $state, $template, and other expressions at render time, against the current state and AppSpec tokens.
5. It wires on action handlers to the action dispatcher.
6. When state changes or a new spec version arrives, only affected subtrees re-render.

The renderer's contract: same spec + same plugins + same state = identical render. This determinism is what lets AI agents iterate on specs with confidence.

Mythik Reveal in React apps

React hosts can expose runtime context to AI agents through the reveal prop. Use it in development when an agent needs to understand what the app is actually rendering:

const reveal = React.useMemo(() => ({
  enabled: import.meta.env.DEV,
  appName: 'backoffice',
  bridgeUrl: import.meta.env.VITE_MYTHIK_REVEAL_URL,
  token: import.meta.env.VITE_MYTHIK_REVEAL_TOKEN,
  environment: { id: 'dev', source: 'host' as const },
  includeStatePaths: ['/ui', '/form'],
  redactStatePaths: ['/auth', '/secrets'],
}), []);

<MythikApp
  appSpec={appSpec}
  specStore={specStore}
  reveal={reveal}
/>;

Start the bridge with npx mythik reveal start, then let the agent run npx mythik reveal context --app backoffice or npx mythik reveal element <id> --app backoffice. Reveal reports live state, resolved public props, events, render errors, and environment metadata so the next patch is based on runtime truth instead of guesswork.

Keep Reveal disabled in production. Memoize the config object, keep the token out of source control, and include only state paths that are useful for diagnosis.

Customization

Register custom primitives, expressions, and action handlers through the plugin hook:

<MythikApp
  appSpec={appSpec}
  specStore={specStore}
  onPlugins={(plugins) => {
    plugins.registerPrimitive('my-custom-card', MyCustomCard);
    plugins.registerExpression('uppercase', (args, ctx) => String(args[0]).toUpperCase());
    plugins.registerAction('analyticsTrack', async (params) => { /* ... */ });
    plugins.setIconRenderer(MyIconRenderer);
  }}
/>

Custom primitives become available as a type value in any spec loaded from your store. Custom expressions and actions can be referenced from any spec. Use these sparingly — every custom hook is code that lives outside the spec store and outside the version-control audit trail.

Related packages

• mythik — the runtime this renderer consumes (peer dependency)
• mythik-cli — author and patch the specs you're rendering
• mythik-server — declarative REST server from an ApiSpec
• mythik-react-native — render supported Mythik primitives in Expo and React Native

Status

Public release line. APIs are documented for real-world feedback as the framework evolves.

Releases

Release notes and patch details are published in the CHANGELOG and on GitHub Releases.

License

Apache-2.0.