mythik-react-native

The React Native and Expo rendering surface for Mythik contracts. Turn validated JSON from your store into native UI, embed a single spec via MythikRenderer, wire native screens through the app shell, and keep the same runtime contract used by the web renderer.

See the framework README on GitHub for the full Mythik architecture and design philosophy. This file documents what mythik-react-native 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 Native rendering surface: it turns those same validated JSON contracts into native app screens.

Install

mythik-react-native follows the same version line as the rest of Mythik, but remains a public preview while native primitive parity and smoke coverage continue to expand. Expo SDK 52, 53, and 54 are the tested SDK line. Expo SDK 55 support is pending React Native 0.82 / Reanimated 4.2 alignment.

For Expo apps, install the native peer packages first so Expo chooses versions that match your SDK:

npx expo install react-native-svg react-native-reanimated react-native-worklets react-native-safe-area-context react-native-screens react-native-gesture-handler expo-linear-gradient expo-haptics expo-blur @react-native-community/slider

Then install Mythik and the native renderer:

npm install mythik mythik-react-native

Keep the Reanimated Babel plugin last in your app's Babel config:

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: ['react-native-reanimated/plugin'],
  };
};

Your Expo or React Native host still owns native project setup, app registration, navigation container wiring, permissions, and app-store packaging. Mythik owns the spec contract and renderer.

What you get

• <MythikRenderer> - single-spec native renderer for embedding Mythik screens inside an Expo or React Native app.

• Native primitive registry - 27 supported primitives covering layout, text/media, forms, interactive surfaces, app structure, overlays, and loading states.

• Explicit support matrix - REACT_NATIVE_PRIMITIVE_SUPPORT and getReactNativePrimitiveSupport(name) tell you whether a primitive is supported natively or belongs to a future native milestone.

• Shared Mythik contract - the renderer consumes the same Spec shape, expression system, state bindings, action chains, transactions, tokens, and validation model used by mythik-react.

• Native runtime hardening - RN-safe background SVG sanitization, portable notification IDs, $platform render-cache invalidation, native-safe motion helpers, and Android overlay behavior tested against a real emulator.

Minimal example

import { MythikRenderer } from 'mythik-react-native';

const spec = {
  root: 'main',
  elements: {
    main: {
      type: 'stack',
      props: { gap: 12, padding: 24 },
      children: ['title', 'subtitle'],
    },
    title: {
      type: 'text',
      props: {
        content: {
          $platform: {
            web: 'Hello web',
            native: 'Hello native',
          },
        },
        variant: 'heading',
      },
    },
    subtitle: {
      type: 'text',
      props: {
        content: 'Rendered from the same Mythik spec contract.',
      },
    },
  },
};

export default function App() {
  return <MythikRenderer spec={spec} />;
}

Keep root as a stable string element id. Use $platform only inside localized props, styles, children, or values. $platform matches the exact platform key first, then falls back from ios/android to native; it does not support a default key.

Supported primitive contract

The native package publishes the support matrix as runtime data:

import {
  REACT_NATIVE_PRIMITIVE_SUPPORT,
  getReactNativePrimitiveSupport,
} from 'mythik-react-native';

console.log(getReactNativePrimitiveSupport('button')?.status);

Supported in the current native renderer:

• Layout: box, stack, grid, scroll, divider, spacer
• Text and media: text, image, icon
• Forms: input, textarea, select, checkbox, toggle, slider, button
• Interactive: touchable, list, modal, drawer, tabs, accordion, wizard
• App structure: screen, screen-outlet, toast-container, skeleton

Native milestone primitives are intentionally visible as unsupported rather than silently pretending parity: bar-chart, line-chart, pie-chart, area-chart, table, kanban-board, spatial-map, file-upload, camera, signature, and audio-player.

If a native spec references a milestone primitive, the renderer should surface diagnostics instead of rendering broken UI. Treat the matrix as part of the public contract.

Platform parity

mythik-react-native consumes the same design tokens as the web renderer where the platform can express them: surface treatments, radius, border and elevation, typography hierarchy, heading color, icon defaults, image defaults, motion recipes, and layered backgrounds.

Some platform differences are real. React Native uses expo-blur for glass surfaces and react-native-svg for SVG background layers. Web CSS-only effects should be guarded with $platform. If the platform experience is fundamentally different, prefer separate screen specs; do not make root dynamic.

Authoring workflow

Specs should be edited through the same CLI loop used by web apps:

mythik manifest <spec-id>
mythik elements <spec-id> <element-id>
mythik patch <spec-id> --from-file patch.json --author <agent>
mythik validate <spec-id>

Do not rewrite whole specs when a small RFC 6902 patch is enough. This is especially important for AI agents: inspect the live contract, patch the smallest valid change, then verify.

For the CLI surface, see mythik-cli. For the web renderer, see mythik-react.

Mythik Reveal in native apps

React Native hosts also support the reveal prop. This is important for native debugging because screenshots and Metro logs rarely explain which spec branch, state path, or unsupported primitive caused the runtime behavior.

const reveal = React.useMemo(() => ({
  enabled: __DEV__,
  appName: 'field-app',
  bridgeUrl: 'http://127.0.0.1:17373',
  token: process.env.EXPO_PUBLIC_MYTHIK_REVEAL_TOKEN,
  environment: { id: 'android-emulator', source: 'host' as const },
  includeStatePaths: ['/ui', '/form'],
  redactStatePaths: ['/auth', '/secrets'],
}), []);

<MythikRenderer spec={spec} reveal={reveal} />;

For Android emulator smoke, map the bridge port to the emulator before loading the app:

adb reverse tcp:17373 tcp:17373
npx mythik reveal start --port 17373
npx mythik reveal context --app field-app

Reveal context includes runtime.platform, the native renderer kind, render errors, the explicit native support diagnostics, selected state paths, and action/dataSource events. Use it before assuming a native issue is a spec problem or a renderer problem.

Keep Reveal development-only and redact sensitive paths. Native apps often carry auth/session state in memory; expose only what the agent needs.

Related packages

• mythik - the runtime this renderer consumes
• mythik-react - render the same specs as a React app
• mythik-cli - author and patch the specs you render
• mythik-server - declarative REST server from an ApiSpec

Status

Public preview release line. The package is published with an explicit support matrix and real Expo/Android smoke coverage, while native milestone primitives remain intentionally outside the supported surface until their platform adapters are complete.

Releases

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

License

Apache-2.0.