The Complete Production SOP: How to Deploy and Run Expo & React Native Mobile Artisan in Autonomous AI Agents
Step-by-step SOP to install and run Expo & React Native Mobile Artisan in Codex, Claude Code, and Cursor. Includes verified prompts, configs, and fixes.
Technical Overview & Architectural Context
Autonomous coding agents frequently generate brittle mobile architectures because they treat React Native like standard web React. Without deterministic domain rules, models like Claude Code, Cursor, and Codex hallucinate obsolete APIs, use DOM elements (<div/>, <span/>), fail to configure native Safe Area contexts, omit essential react-native-reanimated Babel plugins, and misconfigure Expo Router v3 layout hierarchies. This leads to broken Metro bundler sessions, white-screen startup crashes on iOS/Android, and cascading layout clipping. The 'cursor-react-native' skill establishes strict architectural guardrails. It enforces standard React Native primitives (View, Text, Pressable), requires react-native-safe-area-context wrappers for responsive notches and home indicators, ensures native gesture responder chains operate on the UI thread, and configures NativeWind v4 Tailwind setups deterministically. By forcing the agent to inspect the existing project structure and validate dependencies prior to editing code, this skill prevents recurring runtime exceptions and context window degradation.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Create the local skill manifest directory and inject verified procedural rules into your workspace.
Autonomous runtimes parse agent rules from project-level or global configuration paths. For project-scoped execution in Cursor and Windsurf, mount the SKILL.md into `.cursor/rules/` or `.agents/skills/cursor-react-native/SKILL.md`. Claude Code and Codex load procedural manifests from the root or dedicated `.agents/skills` tree. This forces the agent to read operational boundaries before drafting or modifying mobile UI components.
mkdir -p .agents/skills/cursor-react-native && cat << 'EOF' > .agents/skills/cursor-react-native/SKILL.md
---
name: "cursor-react-native"
description: "Build fluid iOS and Android mobile apps with Expo Router v3, NativeWind, and Reanimated."
version: "1.0.0"
category: "fullstack"
triggers:
- "expo mobile component"
- "expo router v3"
- "react native safe area"
- "nativewind styling"
---
# Expo & React Native Mobile Artisan Rules
- Strictly enforce React Native core primitives; never use web DOM primitives (div, span, p).
- Wrap root layouts in SafeAreaProvider and apply useSafeAreaInsets() on flex containers.
- Verify babel.config.js includes 'react-native-reanimated/plugin' as the last plugin.
- Validate NativeWind classes using Tailwind CSS v4 / NativeWind v4 standards.
- Run TypeScript type checks and lint checks before completing tasks.
EOF---
name: "cursor-react-native"
description: "Build fluid iOS and Android mobile apps with Expo Router v3, NativeWind, and Reanimated."
category: "fullstack"
---
# Rules
1. Always wrap screen containers with SafeAreaView or useSafeAreaInsets.
2. Ensure animations leverage react-native-reanimated and run on the UI thread.
3. Verify Expo Router file-based route syntax under app/ directory.
4. Check packages before installing to avoid incompatible native binary modules.Keep the SKILL.md rules succinct. Agents prioritize rules near the top of the context window. Avoid embedding multi-page styling guides that deplete token cache.
In Cursor, ensure the `.cursor/rules/` file contains `globs: **/*.tsx, **/*.ts` so the skill is only injected during mobile codebase editing, preventing context pollution during backend edits.
Environment Secrets & Dependency Validation
Inject required environment variables safely and assert Expo native module compatibility.
Mobile builds fail when native package versions drift from the Expo SDK baseline. The agent must verify that Expo, React Native, and NativeWind share compatible semantic versions. Use `npx expo install --check` inside the workspace to align all native dependencies with the installed Expo SDK.
npx expo install expo react-native nativewind react-native-reanimated react-native-safe-area-context && npx expo install --checkmodule.exports = function (api) {
api.cache(true);
return {
presets: [
['babel-preset-expo', { jsxImportSource: 'nativewind' }],
'nativewind/babel',
],
plugins: [
'react-native-reanimated/plugin',
],
};
};Always use 'npx expo install' instead of standard 'npm install' or 'pnpm add' to allow Expo's package matrix to resolve matching native framework binaries automatically.
Placing 'react-native-reanimated/plugin' anywhere other than the absolute last element in the Babel plugins array triggers undefined worklet errors at runtime.
Intent Matching & Trigger Invocation
Verify deterministic activation using tested natural language prompts and route structures.
Trigger the agent with explicit Expo Router v3 intents. The skill instructs the agent to create typed route files within the `app/` hierarchy and bind responsive safe area containers rather than hardcoded status bar paddings.
claude "Use cursor-react-native to generate an authenticated modal sheet route under app/(modals)/profile.tsx with smooth Reanimated slide-in and NativeWind styles."import React from 'react';
import { View, Text, Pressable } from 'react-native';
import { useRouter } from 'expo-router';
import { useSafeAreaInsets } from 'react-native-safe-area-context';
import Animated, { FadeInDown } from 'react-native-reanimated';
export default function ProfileModal() {
const insets = useSafeAreaInsets();
const router = useRouter();
return (
<View
className="flex-1 bg-neutral-900 px-6"
style={{ paddingTop: insets.top, paddingBottom: insets.bottom }}
>
<Animated.View entering={FadeInDown.duration(300)} className="mt-8">
<Text className="text-2xl font-bold text-white">Profile Settings</Text>
<Text className="text-neutral-400 mt-2">Manage mobile preferences and sync.</Text>
<Pressable
onPress={() => router.back()}
className="mt-6 bg-blue-600 active:bg-blue-700 py-3 rounded-xl items-center"
>
<Text className="text-white font-semibold">Done</Text>
</Pressable>
</Animated.View>
</View>
);
}Explicitly reference screen targets (e.g., 'app/(tabs)/index.tsx' or 'app/(modals)/profile.tsx') in prompts to guide the agent directly to the Expo Router file convention.
Do not let the agent write `import { SafeAreaView } from 'react-native'`. Instruct it to always use `react-native-safe-area-context` to prevent notch overlap issues on modern dynamic islands.
Verification, Linting & Output Quality Gate
Execute automated self-healing checks and TypeScript verification before accepting agent code.
Require the agent to invoke TypeScript and Expo diagnostics to confirm that no uncompiled JSX or non-native HTML elements exist in the workspace before completing the session.
npx tsc --noEmit && npx expo-doctor{
"scripts": {
"verify": "tsc --noEmit && expo-doctor",
"lint": "eslint . --ext .js,.jsx,.ts,.tsx"
}
}Instruct the agent to run `npx expo-doctor` during its self-correction step. It flags incompatible native pods and misaligned SDK packages before physical device testing.
Ensure simulator builds are not running during large file regenerations to avoid Metro bundler lock file collisions (`.metro/cache`).
Real-World Scenario: Scaffolding an Offline-Ready Feed Screen with NativeWind & Reanimated
“Using the cursor-react-native skill, implement an animated product feed screen at app/(tabs)/feed.tsx. It must consume a typed list, provide pull-to-refresh, calculate dynamic Safe Area insets, style items using NativeWind utility classes, and animate item layout mounting with Reanimated.”
Runtime Troubleshooting & Failure Modes
Root Cause: The agent introduced Reanimated hooks without ensuring 'react-native-reanimated/plugin' was listed as the last plugin in babel.config.js, or Metro cache was not cleared after package installation.
npx expo start -c && node -e "console.log('Ensure babel.config.js has react-native-reanimated/plugin as the final entry in plugins array')"Root Cause: Agent hallucinated HTML DOM primitives (div, span) instead of native React Native primitives (View, Text) and attempted to use web-only CSS properties.
sed -i '' 's/<div/<View/g' app/**/*.tsx && sed -i '' 's/<\/div>/<\/View>/g' app/**/*.tsxFrequently Asked Questions (Expo & React Native Mobile Artisan SOP)
Q:Can I use Expo & React Native Mobile Artisan across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification. You can symlink or copy `.agents/skills/cursor-react-native/SKILL.md` into `.cursor/rules/` or Claude Code workspace profiles without modifying the core procedural directives.
Q:How does Expo & React Native Mobile Artisan prevent context window overflow during long agent sessions?
The skill provides precise architectural guardrails rather than embedding massive template codebases into context. It directs agents to leverage official Expo CLI commands and verifies code using local commands (e.g., tsc, expo-doctor) rather than relying on endless prompt generation loops.
Q:Does this skill require escalated root or container permissions?
No. The skill operates entirely within the workspace sandbox with an audited security score of 98/100. It requires standard file read/write permissions and access to workspace Node/Expo commands, avoiding sudo or host-level kernel permissions.
Ready to equip your autonomous agent with Expo & React Native Mobile Artisan?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.