react-native-builder

A minimal TypeScript library starter using Rollup, ESLint (flat), and Prettier.

React Native support (no react-dom)

• Web: import from @developer_tribe/react-builder/web
• React Native: import from @developer_tribe/react-builder (Metro will prefer the react-native export condition)

Embedding the web editor (ProjectPage)

• Sizing: the editor fills calc(100dvh - var(--rb-editor-offset)), where --rb-editor-offset defaults to 60px (one host header bar). Hosts with different chrome can override --rb-editor-offset, or set --rb-editor-height directly, on an ancestor.
• Saving: onSaveProject(project, { draftVersion }) may return a Promise. The version and project tree are captured before the optional asynchronous onSaveProjectColors call. The editor shows a "Saving…" state while the save is pending. When the Promise rejects, it keeps the changes flagged as unsaved and shows "Save failed" in the header, so hosts should re-throw after reporting their own errors. Saving from the header or with ⌘/Ctrl+S shows no toast of its own (neither success nor failure); the header status shows the save state instead.
• Live refresh: pass onDraftChange(dirty, editVersion) when the host receives remote project updates. The editor first reports a clean draft, then reports local edits synchronously with an increasing version. Keep remote revisions pending while dirty is true or a save is in flight; compare the draftVersion passed to onSaveProject before clearing the host's dirty flag. If an edit lands after a host schedules a clean remote update, the editor retains the local tree and calls onRemoteProjectSkipped(incomingData); keep that revision pending for an explicit reload and retain the revision of the tree actually being edited as the save base. A skipped update is not applied automatically when the draft later becomes clean. The reload action loads the current project prop, which may have changed since page load. A host with its own revision banner can pass showReloadCurrentProject={false} to hide the editor's reload action.
• Shortcuts: ⌘/Ctrl+S saves, ⌘/Ctrl+Z undoes, ⇧⌘/Ctrl+Shift+Z (or Ctrl+Y) redoes. They are ignored while a modal dialog ([role="dialog"][aria-modal="true"]) is open, and undo/redo leave text fields to the browser.

When automatically applying a remote tree, wait for onRemoteProjectApplied(incomingData) before using its revision as the save base. Until that acknowledgement, saves must keep the previous revision, and a second remote update should remain pending. onRemoteProjectSkipped requires restoring the previous save base and offering the remote revision for an explicit reload. Migration and validation screens acknowledge the incoming project they represent; a local project override can instead reject a remote tree. The editor applies the loading state, tree, selection and undo baseline before the next paint so input cannot edit the previous tree against the new baseline.

JSON motion

View supports enterAnimation, enterDelayMs, and enterDurationMs. A direct GlobalProvider child View can set persistentLayer to background or foreground to stay mounted across pages. Action buttons support pressEffect, pressScale, pulseScale, pulseDurationMs, shine, shineDurationMs, and native haptic presets. Pages within GlobalProvider support enterDurationMs, exitAnimation, and exitDurationMs; a page with animation: "none" has no automatic transition hold. OnboardImage.posterSrc provides a still image while remote video or Lottie media loads. Values and limits are documented in the mobile builder's packages/builder/docs/cookbook/builder-motion.md; the web and native implementations share the JSON field names.

Remote video in JSON pages

BackgroundImage and Image accept video_url with posterSrc (or src as a still-image fallback). A full-screen BackgroundImage can sit behind text and buttons while an Image displays a separate foreground clip. Both videos loop muted. The still remains visible until the first frame is ready; a video failure leaves it visible. Set resizeMode to cover, contain, or stretch, and supply a poster for remote media. Mobile video playback is supplied by @developer_tribe/builder.

Preview typography

ProjectPage normally selects the main font from typography.fonts for themed components such as buttons. Plain JSON Text and checkbox labels use the preview device's platform font unless JSON specifies fontFamily, matching their native React Native implementation. Pass appFont={null} for a JSON sample whose themed components should also use the platform font. Android previews prefer Roboto and fall back to Noto Sans or Arial; iOS previews use the Apple system font stack. Match the preview device size and app typography when comparing it with a native screen. Missing or malformed typography data is treated as an empty font list so the editor stays open.

Scripts

• build: Clean and bundle to dist/ (CJS + ESM, types)
• build:watch: Watch mode for development
• lint: Run ESLint
• format: Run Prettier
• typecheck: Run TypeScript type checking

Getting started

npm install
npm run build

Project structure

src/
  index.ts
  index.web.ts
rollup.config.mjs
eslint.config.mjs
tsconfig.json
.prettierrc
.gitignore

Publishing

Ensure dist/ is up to date:

npm run build

Then publish as needed.

Remote video in JSON pages

BackgroundImage and Image accept video_url with posterSrc (or src as a still-image fallback). A full-screen BackgroundImage may sit behind text and buttons, while a separate Image can show a foreground clip. Both videos loop muted. The still remains visible until the first frame is ready, including on a slow connection; video failure leaves the still visible. Set resizeMode to cover, contain, or stretch, and provide a poster for every remote video. Mobile video playback is supplied by @developer_tribe/builder.