Imported from burdiuz/react-native-codeditor (SKILL.md). Install upstream with npx skills add burdiuz/react-native-codeditor. Copyright stays with the author (MIT).

@actualwave/react-native-codeditor — Agent Skill

CodeMirror 6 code editor for React Native, embedded in a WebView with a full bidirectional RPC bridge. Fully offline — all CodeMirror assets are bundled. Works on Android and iOS.

Exports

import CodeEditor from '@actualwave/react-native-codeditor';
// or named:
import { CodeEditor } from '@actualwave/react-native-codeditor';

// Types
import type {
  CodeEditorProps,    // all props for <CodeEditor />
  WebViewAPI,         // api object received in onInitialized
  WebViewAPIHandlers, // handler callbacks
  WebViewRef,         // { injectJavaScript, requestFocus? }
  InitialConfig,      // { content?, language?, extensions?, theme?, viewport? }
  EditorAPI,          // full interface of api.editor proxy methods
  ExtensionSpec,      // string | [string, string] | [string, object] | unknown
  ViewportSettings,   // { intialScale?, maximumScale?, minimumScale?, userScalable?, viewportWidth? }
  CursorPosition,     // { line: number, ch: number, index: number }
  HistorySize,        // { undo: number, redo: number }
  CompletionItem,     // { label, type?, detail?, info? }
} from '@actualwave/react-native-codeditor';

Installation

npm install @actualwave/react-native-codeditor react-native-webview

Copy assets to Android (required — WebView loads these files at runtime):

mkdir -p android/app/src/main/assets/codeditor
cp -r node_modules/@actualwave/react-native-codeditor/src/assets/* android/app/src/main/assets/codeditor/

Expo (recommended) — add plugin to app.json, then expo prebuild:

{ "expo": { "plugins": ["@actualwave/react-native-codeditor"] } }

iOS — requires expo-file-system for the runtime bundle path:

npm install expo-file-system

import * as FileSystem from 'expo-file-system';
const IOS_EDITOR_URI = Platform.OS === 'ios'
  ? (FileSystem.bundleDirectory ?? '') + 'assets/codeditor/editor.html'
  : undefined;
<CodeEditor editorUri={IOS_EDITOR_URI} ... />

Android manifest — add adjustResize so the editor shrinks when the keyboard appears:

<activity android:windowSoftInputMode="adjustResize" ... />

After upgrading — always re-copy assets:

cp -r node_modules/@actualwave/react-native-codeditor/src/assets/* android/app/src/main/assets/codeditor/

Basic usage

import { useCallback, useRef } from 'react';
import { KeyboardAvoidingView, Platform } from 'react-native';
import CodeEditor from '@actualwave/react-native-codeditor';
import type { WebViewAPI, HistorySize } from '@actualwave/react-native-codeditor';

export default function EditorScreen() {
  const apiRef = useRef<WebViewAPI | null>(null);

  const handleInitialized = useCallback((api: WebViewAPI) => {
    apiRef.current = api;
    void api.focus(); // opens Android soft keyboard
  }, []);

  return (
    <KeyboardAvoidingView style={{ flex: 1 }} behavior={Platform.OS === 'ios' ? 'padding' : 'height'}>
      <CodeEditor
        content="const x = 42;"
        language="javascript"
        theme="darcula"
        onInitialized={handleInitialized}
        onContentUpdate={(content) => console.log(content.length)}
        onHistorySizeUpdate={(size) => console.log(size.undo, size.redo)}
        onLog={(...args) => console.log('[editor]', ...args)}
        onError={(err) => console.error('[editor]', err)}
      />
    </KeyboardAvoidingView>
  );
}

Architecture

Two runtimes connected via DDA (Deferred Data Access) RPC over the WebView bridge:

React Native (HOST)                WebView (GUEST)
──────────────────                 ───────────────
CodeEditor component
  └─ WebViewAPI
       └─ initializeHost()   ◄──►  initializeGuest()
            api.editor.*  ──────►  EditorController methods
            (DDA proxy)   ◄──────  Promise results

Out-of-band messages (bypass DDA, sent via ReactNativeWebView.postMessage):

DDA lazy mode — critical rule

DDA operates in lazy mode: a proxy call builds a command chain but does NOT send it until the returned value is awaited. Every api.editor.* call MUST be awaited.

// ✅ correct
await apiRef.current?.editor?.historyUndo();

// ✅ correct — async IIFE in useEffect
void (async () => { await apiRef.current!.editor.setLanguage('python'); })();

// ❌ wrong — command is never sent
void apiRef.current?.editor.historyUndo();
apiRef.current?.editor.historyUndo();

Props

Required callbacks

Optional callbacks

Editor configuration

WebView / layout

WebViewAPI — editor control

api is received in onInitialized. api.editor is a DDA proxy — all its methods return Promises.

Focus

api.focus(): Promise<void>
// Also calls webView.requestFocus() for Android keyboard.

Content

api.editor.getValue(): Promise<string>
api.editor.setValue(value: string): Promise<void>        // preserves history
api.editor.resetValue(value?: string): Promise<void>     // clears history

Language / theme / extensions

api.editor.setLanguage(name: string): Promise<void>
api.editor.setTheme(themeName?: string): Promise<void>   // undefined removes theme
api.editor.setExtensions(specs: ExtensionSpec[]): Promise<void>

Cursor and selection

api.editor.getCursor(where?: 'from' | 'to' | 'head'): Promise<CursorPosition>
// CursorPosition = { line: number, ch: number, index: number }  (line is 0-based)
api.editor.setCursor(line: number, ch?: number): Promise<void>
api.editor.getSelection(): Promise<string>
api.editor.setSelection(anchor: number, head?: number): Promise<void>
api.editor.replaceSelection(text: string): Promise<void>
api.editor.cancelSelection(): Promise<void>

History

api.editor.historyUndo(): Promise<boolean>
api.editor.historyRedo(): Promise<boolean>
api.editor.historyClear(): Promise<void>
api.editor.historySize(): Promise<HistorySize>  // { undo, redo }

Editing commands

api.editor.indentMore(): Promise<boolean>
api.editor.indentLess(): Promise<boolean>
api.editor.toggleComment(): Promise<boolean>
api.editor.moveLineUp(): Promise<boolean>
api.editor.moveLineDown(): Promise<boolean>
api.editor.deleteLine(): Promise<boolean>
api.editor.selectLine(): Promise<boolean>
api.editor.selectParentSyntax(): Promise<boolean>

Autocomplete

api.editor.startCompletion(): Promise<void>
api.editor.setCompletions(items: CompletionItem[]): Promise<void>
// CompletionItem = { label, type?, detail?, info? }

Custom shortcuts (hardware keyboard)

Register key bindings from the React Native side. When triggered in the editor, fires onShortcut on the <CodeEditor> component with the given name. Shortcuts use Prec.highest priority, overriding all built-in keymaps.

api.editor.registerShortcut(key: string, name: string): Promise<void>
api.editor.unregisterShortcut(key: string): Promise<void>

Key notation: Mod = Cmd on macOS/iOS, Ctrl on Android/Windows. Examples: 'Mod-s', 'Mod-Enter', 'Mod-Shift-f', 'F5'.

// Register in onInitialized, handle in onShortcut
<CodeEditor
  onInitialized={async (api) => {
    await api.editor.registerShortcut('Mod-s', 'save');
    await api.editor.registerShortcut('Mod-Enter', 'run');
  }}
  onShortcut={(name) => {
    if (name === 'save') handleSave();
    if (name === 'run') handleRun();
  }}
  ...
/>

Font / keyboard / scroll / advanced

api.editor.setFontSize(size: number): Promise<void>
api.editor.setSoftKeyboard(enabled: boolean): Promise<void>
api.editor.setViewport(options: ViewportSettings): Promise<void>
api.editor.scrollToCursor(margin?: number): Promise<void>
api.editor.loadExtension(moduleName: string): Promise<object>
api.editor.destroy(): Promise<void>

Synchronous RN-side only

api.injectJavaScript(code: string): void
api.requestFocus(): void

Content model

content prop is uncontrolled — it sets the initial document once. Do not write onContentUpdate output back to it (causes feedback loop + cursor reset on every keystroke).

To push content programmatically use the API:

await api.editor.setValue(newCode);      // preserve history
await api.editor.resetValue(newCode);    // clear history (e.g. opening new file)

Extension specs

ExtensionSpec accepted by extensions prop and api.editor.setExtensions():

Built-in registry: @codemirror/autocomplete, @codemirror/search, @codemirror/lint, @codemirror/collab, @codemirror/theme-one-dark.

Supported languages

angular cpp css go html java javascript jinja json less lezer liquid markdown php python rust sass sksl sql vue wast xml yaml

Legacy modes (100+ more) via loadExtension:

const { swift } = await api.editor.loadExtension('@codemirror/legacy-modes/mode/swift');

Themes

androidstudio andromeda atomone aura basic bbedit copilot darcula dracula duotone eclipse github monokai nord okaidia solarized sublime tokyoNight vscode xcode

Two-word themes use camelCase: tokyoNight, githubDark, githubLight, vscodeDark, xcodeDark, xcodeLight, solarizedDark, solarizedLight.

Built-in keyboard shortcuts

The editor ships with standard CodeMirror 6 keymaps active by default.

Editing (defaultKeymap)

History (historyKeymap)

Search (searchKeymap)

Code folding (foldKeymap)

Autocomplete (completionKeymap)

On mobile, most shortcuts require a hardware keyboard. Use api.editor.* commands programmatically instead.

Keyboard / layout

Wrap in KeyboardAvoidingView so the editor shrinks when the soft keyboard appears:

<KeyboardAvoidingView style={{ flex: 1 }} behavior={Platform.OS === 'ios' ? 'padding' : 'height'}>
  <CodeEditor ... />
</KeyboardAvoidingView>

Call api.focus() inside onInitialized to trigger the Android soft keyboard immediately.

Common pitfalls

DDA calls not dispatched — forgetting await silently does nothing. Every api.editor.* must be awaited.

onInitialized timing — api is not available until this fires. Guard all API calls with if (!apiRef.current) return.

Content feedback loop — do not pass onContentUpdate output back to the content prop.

Android assets not copied — if the WebView shows "Error loading page", the src/assets/ files haven't been copied to android/app/src/main/assets/codeditor/. Re-run the copy command.

iOS URI — the default editorUri is Android-only. iOS requires FileSystem.bundleDirectory + 'assets/codeditor/editor.html' from expo-file-system.

Upgrading the library — always re-copy assets after upgrading:

cp -r node_modules/@actualwave/react-native-codeditor/src/assets/* android/app/src/main/assets/codeditor/