Stop Your AI Agent Writing 2023 React Native: A CLAUDE.md for Expo + Supabase Apps

A developer published a CLAUDE.md project rules file for Expo + Supabase apps that steers AI coding agents away from deprecated React Native patterns such as expo-av, core SafeAreaView, and AsyncStorage token storage. The file specifies npx expo install over npm install, Expo Router with Stack.Protected auth guards, Supabase RLS and generated types, and a pre-completion check running tsc, expo lint, and expo-doctor.

Ask an AI coding agent to "add a video player" to your Expo app, and there's a good chance it reaches for expo-av . Ask for a login screen, and it may store the session token in plain AsyncStorage, wrap the screen in SafeAreaView from react-native , and install packages with npm install instead of npx expo install . None of that is the agent being careless. It's the agent averaging over years of tutorials, most of which were written for older versions of React Native and Expo. The fix is cheap: a project rules file. Claude Code reads CLAUDE.md at the start of every session, and other agents read similar files AGENTS.md , Cursor rules . A rules file tells the agent how this project works, so it stops guessing. Here's one built for Expo + Supabase apps, section by section, then the checks that catch what still slips through. expo-image , not Image from react-native " changes the output. Copy this into the root of your project and edit it to match your stack. Project rules Stack - Expo managed workflow, development builds + TypeScript strict - Expo Router for navigation file-based, in /app . Do NOT add React Navigation directly. - Supabase for auth, database, and storage. Client in /lib/supabase.ts. Packages - Install with npx expo install <pkg , never npm install , so versions match the SDK. - Before adding a dependency, check if Expo already provides one. - Use: expo-image images , expo-video / expo-audio media; NOT expo-av , react-native-safe-area-context NOT SafeAreaView from react-native , react-native-reanimated animations , expo-secure-store tokens/secrets . Navigation - Screens live in /app. Layouts in layout.tsx. - Auth gating uses Stack.Protected guards in app/ layout.tsx. No useEffect redirects. - Navigate with <Link href or router.push. Use typed routes. Supabase - Never use the secret/service key in the app. Only the publishable key. - Every new table: enable RLS in the same migration, with policies. - Schema changes go in supabase/migrations/, never only in the dashboard. - After a schema change, regenerate types: npm run db:types . - Pass the generated Database type to createClient. No any for query results. Code style - Function components and hooks only. - Handle loading, empty, and error states for every screen that fetches data. - Every user-facing string that requests a permission needs a clear reason. - No inline secrets. Public config uses EXPO PUBLIC ; everything else stays on the server. Before you say you're done Run these and fix any failures: - npx tsc --noEmit - npx expo lint - npx expo-doctor npx expo install picks versions compatible with your Expo SDK. Plain npm install grabs the latest, which is how you end up with a native module that doesn't match your SDK and a build that fails in EAS. The "use X, not Y" list is the highest-value part of the whole file. Each line replaces a deprecated or weaker default the agent would otherwise pick: | Agents often write | Current choice | |---|---| | expo-av | expo-video and expo-audio expo-av is deprecated | | SafeAreaView from react-native | react-native-safe-area-context the core one is deprecated | | Image from react-native | expo-image caching, placeholders, better formats | | Animated API | react-native-reanimated | | Tokens in AsyncStorage | expo-secure-store for anything sensitive | Update this table when you upgrade SDKs. It's the part that ages fastest. Agents trained on years of React Navigation code will happily add a NavigationContainer to an Expo Router app. One line prevents it. The auth rule matters too: protected routes handle redirects and history correctly, while scattered useEffect redirects cause flashes and back-button bugs. These four rules prevent the mistakes that actually hurt: This is the section that changes agent behavior the most. Claude Code runs commands, so when the rules say "run these and fix failures," it type-checks and lints its own work before handing it back. expo-doctor also catches dependency versions that don't match your SDK. A rules file reduces mistakes; it doesn't remove them. When reviewing agent-written Expo code, check these first: key , secret , and token . npx expo install ? AI agents write React Native the way the internet wrote it, which is often a few versions behind. A one-page CLAUDE.md tells them how your project works today: which packages, which navigation, which security rules, and how to check their own work. If you'd rather start from a project that already follows these conventions, AppLighter's Expo + Supabase templates https://applighter.com/?utm source=devto&utm medium=article&utm campaign=claude md expo come with Expo Router, Supabase auth, and RLS set up, so your agent builds on a clean base. What's the one rule your agent keeps breaking? Drop it in the comments.