{"slug": "stop-your-ai-agent-writing-2023-react-native-a-claude-md-for-expo-supabase-apps", "title": "Stop Your AI Agent Writing 2023 React Native: A CLAUDE.md for Expo + Supabase Apps", "summary": "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.", "body_md": "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`.\n\nNone 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.\n\nThe 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.\n\nHere's one built for Expo + Supabase apps, section by section, then the checks that catch what still slips through.\n\n`expo-image`, not `Image` from `react-native`\" changes the output.\nCopy this into the root of your project and edit it to match your stack.\n\n```\n# Project rules\n\n## Stack\n- Expo (managed workflow, development builds) + TypeScript (strict)\n- Expo Router for navigation (file-based, in /app). Do NOT add React Navigation directly.\n- Supabase for auth, database, and storage. Client in /lib/supabase.ts.\n\n## Packages\n- Install with `npx expo install <pkg>`, never `npm install`, so versions match the SDK.\n- Before adding a dependency, check if Expo already provides one.\n- Use: expo-image (images), expo-video / expo-audio (media; NOT expo-av),\n  react-native-safe-area-context (NOT SafeAreaView from react-native),\n  react-native-reanimated (animations), expo-secure-store (tokens/secrets).\n\n## Navigation\n- Screens live in /app. Layouts in _layout.tsx.\n- Auth gating uses Stack.Protected guards in app/_layout.tsx. No useEffect redirects.\n- Navigate with <Link href> or router.push. Use typed routes.\n\n## Supabase\n- Never use the secret/service key in the app. Only the publishable key.\n- Every new table: enable RLS in the same migration, with policies.\n- Schema changes go in supabase/migrations/, never only in the dashboard.\n- After a schema change, regenerate types: `npm run db:types`.\n- Pass the generated Database type to createClient. No `any` for query results.\n\n## Code style\n- Function components and hooks only.\n- Handle loading, empty, and error states for every screen that fetches data.\n- Every user-facing string that requests a permission needs a clear reason.\n- No inline secrets. Public config uses EXPO_PUBLIC_*; everything else stays on the server.\n\n## Before you say you're done\nRun these and fix any failures:\n- `npx tsc --noEmit`\n- `npx expo lint`\n- `npx expo-doctor`\n```\n\n`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.\n\nThe \"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:\n\n| Agents often write | Current choice | \n|---|---|\n| `expo-av` | `expo-video` and`expo-audio` (`expo-av` is deprecated) | \n| `SafeAreaView` from`react-native` | `react-native-safe-area-context` (the core one is deprecated) | \n| `Image` from`react-native` | `expo-image` (caching, placeholders, better formats) | \n| `Animated` API | `react-native-reanimated` | \n| Tokens in AsyncStorage | `expo-secure-store` for anything sensitive | \n\nUpdate this table when you upgrade SDKs. It's the part that ages fastest.\n\nAgents 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.\n\nThese four rules prevent the mistakes that actually hurt:\n\nThis 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.\n\nA rules file reduces mistakes; it doesn't remove them. When reviewing agent-written Expo code, check these first:\n\n`key`, `secret`, and `token`.` npx expo install`?\nAI 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.\n\nIf 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.\n\n*What's the one rule your agent keeps breaking? Drop it in the comments.*", "url": "https://wpnews.pro/news/stop-your-ai-agent-writing-2023-react-native-a-claude-md-for-expo-supabase-apps", "canonical_source": "https://dev.to/hugo_rus_630dd942fcf7cc62/stop-your-ai-agent-writing-2023-react-native-a-claudemd-for-expo-supabase-apps-3fia", "published_at": "2026-10-15 11:37:49+00:00", "updated_at": "2026-10-15 11:49:07.181548+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "large-language-models"], "entities": ["Claude Code", "Expo", "Supabase", "React Native", "Expo Router", "expo-av", "expo-video", "expo-secure-store"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/stop-your-ai-agent-writing-2023-react-native-a-claude-md-for-expo-supabase-apps", "markdown": "https://wpnews.pro/news/stop-your-ai-agent-writing-2023-react-native-a-claude-md-for-expo-supabase-apps.md", "text": "https://wpnews.pro/news/stop-your-ai-agent-writing-2023-react-native-a-claude-md-for-expo-supabase-apps.txt", "jsonld": "https://wpnews.pro/news/stop-your-ai-agent-writing-2023-react-native-a-claude-md-for-expo-supabase-apps.jsonld"}}