Skip to content
Back to search

zafer-skills

SkillWorks with Claude CodeGitHub

Expo React Native mobile app development with StoreKit 2 subscriptions (expo-iap) plus RevenueCat observer mode, AdMob ads with UMP/ATT consent, PostHog analytics, i18n with RTL, onboarding flow, paywall, and NativeTabs navigation

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zaferayan--skills/badge.svg)](/listings/zaferayan--skills)

HTML

<a href="/listings/zaferayan--skills"><img src="/api/listings/zaferayan--skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx skills add zaferayan/skills

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 903 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: zafer-skills
  3. description: Expo React Native mobile app development with StoreKit 2 subscriptions (expo-iap) plus RevenueCat observer mode, AdMob ads with UMP/ATT consent, PostHog analytics, i18n with RTL, onboarding flow, paywall, and NativeTabs navigation
  4. ---
  5. # Expo Mobile Application Development Guide
  6. > **IMPORTANT**: This is a SKILL file, NOT a project. NEVER run npm/bun install in this folder. NEVER create code files here. When creating a new project, ALWAYS ask the user for the project path first or create it in a separate directory (e.g., `~/Projects/app-name`).
  7. This guide is created to provide context when working with Expo projects using Claude Code.
  8. ## MANDATORY REQUIREMENTS
  9. When creating a new Expo project, you MUST include ALL of the following:
  10. ### Required Screens (ALWAYS CREATE)
  11. - [ ] `src/app/onboarding.tsx` - Swipe-based onboarding with fullscreen background video and gradient overlay
  12. - [ ] `src/app/notification-permission.tsx` - Pre-permission screen that explains notifications before the system prompt (add `location-permission.tsx` too if the app uses location)
  13. - [ ] `src/app/paywall.tsx` - Paywall screen (shown after the permission screens)
  14. - [ ] `src/app/settings.tsx` - Settings screen with language, theme, notifications, and reset onboarding options
  15. ### Onboarding Video Implementation (REQUIRED)
  16. The onboarding screen MUST have a fullscreen background video. Use a URL, not a local file:
  17. ```tsx
  18. import { useVideoPlayer, VideoView } from "expo-video";
  19. const VIDEO_URL =
  20. "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4";
  21. const player = useVideoPlayer(VIDEO_URL, (player) => {
  22. player.loop = true;
  23. player.muted = true;
  24. player.play();
  25. });
  26. // In render:
  27. <VideoView
  28. player={player}
  29. style={StyleSheet.absoluteFill}
  30. contentFit="cover"
  31. nativeControls={false}
  32. />;
  33. ```
  34. Do NOT just import expo-video without actually using the VideoView component.
  35. ### Required Navigation (ALWAYS USE)
  36. - [ ] Use `NativeTabs` from `expo-router/unstable-native-tabs` for tab navigation - NEVER use `@react-navigation/bottom-tabs` or `Tabs` from expo-router
  37. ### Required Context Providers (ALWAYS WRAP)
  38. ```tsx
  39. import { ThemeProvider } from "@/context/theme-context";
  40. import {
  41. DarkTheme,
  42. DefaultTheme,
  43. ThemeProvider as NavigationThemeProvider,
  44. } from "@react-navigation/native";
  45. <ThemeProvider>
  46. <OnboardingProvider>
  47. <AdsProvider>
  48. <NavigationThemeProvider
  49. value={colorScheme === "dark" ? DarkTheme : DefaultTheme}
  50. >
  51. <Stack />
  52. </NavigationThemeProvider>
  53. </AdsProvider>
  54. </OnboardingProvider>
  55. </ThemeProvider>;
  56. ```
  57. `AdsProvider` must be inside `OnboardingProvider`: it waits for onboarding to finish before showing the consent form / ATT prompt (see Ads Consent).
  58. ### Required Libraries (ALWAYS INSTALL)
  59. Use `npx expo install` to install libraries (NOT npm/yarn/bun install):
  60. ```bash
  61. npx expo install expo-iap react-native-purchases react-native-google-mobile-ads expo-tracking-transparency expo-notifications i18next react-i18next expo-localization react-native-reanimated expo-video expo-audio expo-sqlite expo-linear-gradient expo-store-review expo-updates expo-dev-client posthog-react-native expo-haptics
  62. ```
  63. Libraries:
  64. - `expo-iap` (StoreKit 2 / Play Billing - purchases and premium check)
  65. - `react-native-purchases` (RevenueCat - observer mode only: purchase records + Apple Ads attribution)
  66. - `react-native-google-mobile-ads` (AdMob + Google UMP consent)
  67. - `expo-tracking-transparency` (iOS ATT prompt)
  68. - `posthog-react-native` (analytics, error tracking, feature flags)
  69. - `expo-store-review` (native rating prompt)
  70. - `expo-updates` (reload after RTL/LTR change), `expo-dev-client`
  71. - `expo-haptics`
  72. - `expo-notifications`
  73. - `i18next` + `react-i18next` + `expo-localization`
  74. - `react-native-reanimated`
  75. - `expo-video` + `expo-audio`
  76. - `expo-sqlite` (for localStorage)
  77. - `expo-linear-gradient` (for gradient overlays)
  78. ### AdMob Configuration (REQUIRED in app.json)
  79. You MUST add this to `app.json` for AdMob to work:
  80. ```json
  81. {
  82. "expo": {
  83. "plugins": [
  84. [
  85. "react-native-google-mobile-ads",
  86. {
  87. "androidAppId": "ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy",
  88. "iosAppId": "ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"
  89. }
  90. ]
  91. ]
  92. }
  93. }
  94. ```
  95. For development/testing, use test App IDs:
  96. - iOS: `ca-app-pub-3940256099942544~1458002511`
  97. - Android: `ca-app-pub-3940256099942544~3347511713`
  98. Do NOT skip this configuration or the app will crash with `GADInvalidInitializationException`.
  99. Also add these plugins (ATT text is mandatory on iOS when ads can be personalised):
  100. ```json
  101. [
  102. "expo-tracking-transparency",
  103. {
  104. "userTrackingPermission": "Your permission lets us show ads that are more relevant to you. If you decline, you can keep using the app and will see less relevant ads."
  105. }
  106. ],
  107. "expo-iap"
  108. ```
  109. ### Banner Ad Implementation (REQUIRED)
  110. Put the banner in its own component and float it above the tab bar in the Tab layout:
  111. ```tsx
  112. // src/components/banner-ad.tsx
  113. import { useState } from 'react';
  114. import { View, StyleSheet } from 'react-native';
  115. import { BannerAd, BannerAdSize, TestIds } from 'react-native-google-mobile-ads';
  116. import { useAds } from '@/context/ads-context';
  117. import { AD_UNIT_IDS } from '@/lib/ads';
  118. export function AdBanner() {
  119. const { isAdsEnabled } = useAds();
  120. const [loaded, setLoaded] = useState(false);
  121. if (!isAdsEnabled) return null;
  122. return (
  123. // Hidden until filled, so an empty slot never takes space
  124. <View style={[styles.container, !loaded && styles.hidden]}>
  125. <BannerAd
  126. unitId={__DEV__ ? TestIds.BANNER : AD_UNIT_IDS.BANNER ?? TestIds.BANNER}
  127. size={BannerAdSize.ANCHORED_ADAPTIVE_BANNER}
  128. // Personalisation follows the UMP + ATT choice; do NOT force requestNonPersonalizedAdsOnly
  129. onAdLoaded={() => setLoaded(true)}
  130. onAdFailedToLoad={() => setLoaded(false)}
  131. />
  132. </View>
  133. );
  134. }
  135. const styles = StyleSheet.create({
  136. container: { alignItems: 'center', width: '100%' },
  137. hidden: { opacity: 0, height: 0 },
  138. });
  139. ```
  140. ```tsx
  141. // src/app/(tabs)/_layout.tsx
  142. import { I18nManager, Platform, StyleSheet, View } from 'react-native';
  143. import { usePathname } from 'expo-router';
  144. import { NativeTabs } from 'expo-router/unstable-native-tabs';
  145. import { useSafeAreaInsets } from 'react-native-safe-area-context';
  146. import { useTranslation } from 'react-i18next';
  147. import { AdBanner } from '@/components/banner-ad';
  148. const TAB_BAR_HEIGHT = Platform.OS === 'ios' ? 49 : 56;
  149. export default function TabLayout() {
  150. const { t } = useTranslation();
  151. const insets = useSafeAreaInsets();
  152. // Hide the banner on screens where it would get in the way (camera, compass, full-screen media...)
  153. const showBanner = usePathname() !== '/camera';
  154. return (
  155. <View style={styles.container}>
  156. <NativeTabs
  157. // The native tab bar ignores React Native's RTL setting
  158. unstable_nativeProps={{ direction: I18nManager.isRTL ? 'rtl' : 'ltr' }}
  159. >
  160. <NativeTabs.Trigger name="index">
  161. <NativeTabs.Trigger.Label>{t('tabs.home')}</NativeTabs.Trigger.Label>
  162. <NativeTabs.Trigger.Icon sf="house.fill" md="home" />
  163. </NativeTabs.Trigger>
  164. <NativeTabs.Trigger name="settings">
  165. <NativeTabs.Trigger.Label>{t('tabs.settings')}</NativeTabs.Trigger.Label>
  166. <NativeTabs.Trigger.Icon sf="gear" md="settings" />
  167. </NativeTabs.Trigger>
  168. </NativeTabs>
  169. {showBanner && (
  170. <View style={[styles.banner, { bottom: TAB_BAR_HEIGHT + insets.bottom }]}>
  171. <AdBanner />
  172. </View>
  173. )}
  174. </View>
  175. );
  176. }
  177. const styles = StyleSheet.create({
  178. container: { flex: 1 },
  179. banner: { position: 'absolute', left: 0, right: 0, alignItems: 'center' },
  180. });
  181. ```
  182. - ALWAYS use `TestIds.BANNER` in development
  183. - Banner floats right above the tab bar (`TAB_BAR_HEIGHT + insets.bottom`); give scroll content enough bottom padding
  184. - `useAds().isAdsEnabled` is false for premium users and until consent + SDK init are done
  185. ### Ads Consent: UMP + ATT (REQUIRED)
  186. Ads must not be initialised before consent. Order: **Google UMP form (EU/UK GDPR) → iOS ATT prompt → `mobileAds().initialize()`**. Run it only after onboarding is finished, so it does not stack on top of the permission screens, and skip it entirely for premium users.
  187. ```ts
  188. // src/lib/ads-consent.ts
  189. import { Platform } from 'react-native';
  190. import { AdsConsent, AdsConsentDebugGeography, AdsConsentPrivacyOptionsRequirementStatus } from 'react-native-google-mobile-ads';
  191. import * as TrackingTransparency from 'expo-tracking-transparency';
  192. // Test the EU form from anywhere: EXPO_PUBLIC_ADS_DEBUG_EEA=1 bun start (simulator / test devices only)
  193. const DEBUG_EEA = __DEV__ && process.env.EXPO_PUBLIC_ADS_DEBUG_EEA === '1';
  194. export async function gatherAdsConsent() {
  195. let canRequestAds = false;
  196. let privacyOptionsRequired = false;
  197. try {
  198. const info = await AdsConsent.gatherConsent(DEBUG_EEA ? { debugGeography: AdsConsentDebugGeography.EEA } : undefined);
  199. canRequestAds = info.canRequestAds;
  200. privacyOptionsRequired = info.privacyOptionsRequirementStatus === AdsConsentPrivacyOptionsRequirementStatus.REQUIRED;
  201. } catch {
  202. // Offline: fall back to the previous session's decision
  203. canRequestAds = (await AdsConsent.getConsentInfo().catch(() => null))?.canRequestAds ?? false;
  204. }
  205. // ATT only if ads will be shown; declining still shows (non-personalised) ads
  206. if (canRequestAds && Platform.OS === 'ios' && TrackingTransparency.isAvailable()) {
  207. const { status } = await TrackingTransparency.getTrackingPermissionsAsync();
  208. if (status === 'undetermined') await TrackingTransparency.requestTrackingPermissionsAsync();
  209. }
  210. return { canRequestAds, privacyOptionsRequired };
  211. }
  212. export const showAdsPrivacyOptions = () => AdsConsent.showPrivacyOptionsForm();
  213. ```
  214. In `AdsProvider`:
  215. - Check premium first (cached value, then store) - premium users never see the consent form
  216. - After `gatherAdsConsent()` returns `canRequestAds`, call `mobileAds().setRequestConfiguration({ maxAdContentRating: MaxAdContentRating.PG, ... })` then `mobileAds().initialize()`
  217. - Expose `isAdsEnabled`, `isPremium`, `privacyOptionsRequired`, `showPrivacyOptions`, `refreshPremiumStatus`
  218. - Keep ads OFF in development by default (`__DEV__ && process.env.EXPO_PUBLIC_ADS_DEV !== '1'`)
  219. - Settings MUST show a "Privacy choices" row when `privacyOptionsRequired` is true (EU rule)
  220. - The consent form content is configured in AdMob console → Privacy & messaging
  221. ### TURKISH LOCALIZATION (IMPORTANT)
  222. When writing `tr.json`, you MUST use correct Turkish characters:
  223. - ı (lowercase dotless i) - NOT i
  224. - İ (uppercase dotted I) - NOT I
  225. - ü, Ü, ö, Ö, ç, Ç, ş, Ş, ğ, Ğ
  226. Example:
  227. - ✅ "Ayarlar", "Giriş", "Çıkış", "Başla", "İleri", "Güncelle"
  228. - ❌ "Ayarlar", "Giris", "Cikis", "Basla", "Ileri", "Guncelle"
  229. ### FORBIDDEN (NEVER USE)
  230. - ❌ AsyncStorage - Use `expo-sqlite/localStorage/install` instead
  231. - ❌ lineHeight style - Use padding/margin instead
  232. - ❌ `Tabs` from expo-router - Use `NativeTabs` instead
  233. - ❌ `@react-navigation/bottom-tabs` - Use `NativeTabs` instead
  234. - ❌ `expo-av` - Use `expo-video` for video, `expo-audio` for audio instead
  235. - ❌ `expo-ads-admob` - Use `react-native-google-mobile-ads` instead
  236. - ❌ Any other ads library - ONLY use `react-native-google-mobile-ads`
  237. - ❌ Reanimated hooks inside callbacks - Call at component top level
  238. - ❌ Hardcoded prices or discount badges on the paywall - Always use store-formatted prices (`displayPrice`)
  239. - ❌ Calling `mobileAds().initialize()` before UMP consent
  240. - ❌ Unsupervised `react-native-purchases` purchase calls (`purchasePackage`) - RevenueCat runs in observer mode, purchases go through `expo-iap`
  241. ### Reanimated Usage (IMPORTANT)
  242. NEVER call `useAnimatedStyle`, `useSharedValue`, or other reanimated hooks inside callbacks, loops, or conditions.
  243. ❌ WRONG:
  244. ```tsx
  245. const renderItem = () => {
  246. const animatedStyle = useAnimatedStyle(() => ({ opacity: 1 })); // ERROR!
  247. return <Animated.View style={animatedStyle} />;
  248. };
  249. ```
  250. ✅ CORRECT:
  251. ```tsx
  252. function MyComponent() {
  253. const animatedStyle = useAnimatedStyle(() => ({ opacity: 1 })); // Top level
  254. return <Animated.View style={animatedStyle} />;
  255. }
  256. ```
  257. For lists, create a separate component for each item:
  258. ```tsx
  259. function AnimatedItem({ item }) {
  260. const animatedStyle = useAnimatedStyle(() => ({ opacity: 1 }));
  261. return <Animated.View style={animatedStyle}>{item.name}</Animated.View>;
  262. }
  263. // In FlatList:
  264. renderItem={({ item }) => <AnimatedItem item={item} />}
  265. ```
  266. ### POST-CREATION CLEANUP (ALWAYS DO)
  267. After creating a new Expo project, you MUST:
  268. 1. If using `(tabs)` folder, DELETE `src/app/index.tsx` to avoid route conflicts:
  269. ```bash
  270. rm src/app/index.tsx
  271. ```
  272. 2. Check and remove `lineHeight` from these files:
  273. - `src/components/themed-text.tsx` (comes with lineHeight by default - REMOVE IT)
  274. - Any other component using `lineHeight`
  275. Search and remove all `lineHeight` occurrences:
  276. ```bash
  277. grep -r "lineHeight" src/
  278. ```
  279. Replace with padding or margin instead.
  280. ### AFTER COMPLETING CODE (ALWAYS RUN)
  281. When you finish writing/modifying code, you MUST run these commands in order:
  282. ```bash
  283. npx expo install --fix
  284. npx expo prebuild --clean
  285. ```
  286. 1. `install --fix` fixes dependency version mismatches
  287. 2. `prebuild --clean` recreates ios and android folders
  288. Do NOT skip these steps.
  289. ---
  290. ## Project Creation
  291. When user asks to create an app, you MUST:
  292. 1. FIRST ask for the bundle ID (e.g., "What is the bundle ID? Example: com.company.appname")
  293. 2. Create the project in the CURRENT directory using:
  294. ```bash
  295. bunx create-expo -t default@next app-name
  296. ```
  297. The current baseline is Expo SDK 57 / React Native 0.86 / React 19.2 (New Architecture only). Enable the React Compiler and typed routes in `app.json`:
  298. ```json
  299. {
  300. "expo": {
  301. "experiments": { "typedRoutes": true, "reactCompiler": true },
  302. "ios": {
  303. "infoPlist": {
  304. "ITSAppUsesNonExemptEncryption": false,
  305. "CFBundleAllowMixedLocalizations": true
  306. }
  307. }
  308. }
  309. }
  310. ```
  311. 3. Update `app.json` with the bundle ID:
  312. ```json
  313. {
  314. "expo": {
  315. "ios": {
  316. "bundleIdentifier": "com.company.appname"
  317. },
  318. "android": {
  319. "package": "com.company.appname"
  320. }
  321. }
  322. }
  323. ```
  324. 4. Then cd into the project and start implementing all required screens
  325. 5. Do NOT ask for project path - always use current directory
  326. ## Technology Stack
  327. - **Framework**: Expo, React Native
  328. - **Navigation**: Expo Router (file-based routing), NativeTabs
  329. - **State Management**: React Context API
  330. - **Translations**: i18next, react-i18next
  331. - **Purchases**: StoreKit 2 / Play Billing via `expo-iap` (source of truth for premium)
  332. - **Purchase records & Apple Ads attribution**: RevenueCat in observer mode (`react-native-purchases`)
  333. - **Advertisements**: Google AdMob (react-native-google-mobile-ads) + UMP consent + ATT
  334. - **Analytics**: PostHog (`posthog-react-native`, EU host) - events, screens, error tracking, feature flags
  335. - **Ratings**: `expo-store-review`
  336. - **Notifications**: expo-notifications
  337. - **Animations**: react-native-reanimated
  338. - **Storage**: localStorage via expo-sqlite polyfill
  339. > **WARNING**: DO NOT USE AsyncStorage! Use expo-sqlite polyfill instead.
  340. - Example usage
  341. ```js
  342. import "expo-sqlite/localStorage/install";
  343. globalThis.localStorage.setItem("key", "value");
  344. console.log(globalThis.localStorage.getItem("key")); // 'value'
  345. ```
  346. > **WARNING**: NEVER USE `lineHeight`! It causes layout issues in React Native. Use padding or margin instead.
  347. ## Project Structure
  348. ```
  349. project-root/
  350. ├── src/
  351. │ ├── app/
  352. │ │ ├── _layout.tsx
  353. │ │ ├── index.tsx
  354. │ │ ├── explore.tsx
  355. │ │ ├── settings.tsx
  356. │ │ ├── paywall.tsx
  357. │ │ ├── notification-permission.tsx
  358. │ │ └── onboarding.tsx
  359. │ ├── components/
  360. │ │ ├── ui/
  361. │ │ ├── themed-text.tsx
  362. │ │ └── themed-view.tsx
  363. │ ├── constants/
  364. │ │ ├── theme.ts
  365. │ │ └── [data-files].ts
  366. │ ├── context/
  367. │ │ ├── onboarding-context.tsx
  368. │ │ └── ads-context.tsx
  369. │ ├── hooks/
  370. │ │ ├── use-notifications.ts
  371. │ │ └── use-color-scheme.ts
  372. │ ├── lib/
  373. │ │ ├── notifications.ts
  374. │ │ ├── purchases.ts # expo-iap (StoreKit 2)
  375. │ │ ├── revenuecat.ts # observer mode
  376. │ │ ├── premium-cache.ts
  377. │ │ ├── ads.ts
  378. │ │ ├── ads-consent.ts # UMP + ATT
  379. │ │ ├── analytics.ts # PostHog
  380. │ │ ├── rating.ts # expo-store-review
  381. │ │ └── i18n.ts
  382. │ └── locales/
  383. │ ├── tr.json
  384. │ └── en.json
  385. ├── assets/
  386. │ └── images/
  387. ├── ios/
  388. ├── android/
  389. ├── app.json
  390. ├── eas.json
  391. ├── store.config.json # EAS Metadata (App Store listing)
  392. ├── package.json
  393. └── tsconfig.json
  394. ```
  395. ## Tab Navigation (NativeTabs)
  396. Expo Router uses NativeTabs for native tab navigation:
  397. ```tsx
  398. import { NativeTabs } from "expo-router/unstable-native-tabs";
  399. export default function TabLayout() {
  400. return (
  401. <NativeTabs>
  402. <NativeTabs.Trigger name="index">
  403. <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
  404. <NativeTabs.Trigger.Icon sf="house.fill" md="home" />
  405. </NativeTabs.Trigger>
  406. <NativeTabs.Trigger name="explore">
  407. <NativeTabs.Trigger.Label>Explore</NativeTabs.Trigger.Label>
  408. <NativeTabs.Trigger.Icon sf="compass.fill" md="explore" />
  409. </NativeTabs.Trigger>
  410. <NativeTabs.Trigger name="settings">
  411. <NativeTabs.Trigger.Label>Settings</NativeTabs.Trigger.Label>
  412. <NativeTabs.Trigger.Icon sf="gear" md="settings" />
  413. </NativeTabs.Trigger>
  414. </NativeTabs>
  415. );
  416. }
  417. ```
  418. ### NativeTabs Properties
  419. - **sf**: SF Symbols icon name (iOS)
  420. - **md**: Material Design icon name (Android)
  421. - **name**: Route file name
  422. - Tab order follows trigger order
  423. - RTL: pass `unstable_nativeProps={{ direction: I18nManager.isRTL ? 'rtl' : 'ltr' }}`, the native bar does not follow `I18nManager` on its own
  424. - If NativeTabs misbehaves on Android, fall back to expo-router `Tabs` **on Android only** (`if (Platform.OS === 'ios') return <NativeTabs>...`) with `IconSymbol` icons and a haptic tab button; iOS always uses NativeTabs
  425. ### Common Icons
  426. | Purpose | SF Symbol | Material Icon |
  427. | ------------- | --------------- | ------------- |
  428. | Home | house.fill | home |
  429. | Explore | compass.fill | explore |
  430. | Settings | gear | settings |
  431. | Profile | person.fill | person |
  432. | Search | magnifyingglass | search |
  433. | Favorites | heart.fill | favorite |
  434. | Notifications | bell.fill | notifications |
  435. ## Development Commands
  436. ```bash
  437. bun install
  438. bun start
  439. bun ios
  440. bun android
  441. bun lint
  442. npx expo install --fix
  443. npx expo prebuild --clean
  444. ```
  445. ## EAS Build Commands
  446. `eas.json` baseline:
  447. ```json
  448. {
  449. "cli": { "version": ">= 16.28.0", "appVersionSource": "remote", "promptToConfigurePushNotifications": false },
  450. "build": {
  451. "development": { "developmentClient": true, "distribution": "internal" },
  452. "preview": { "distribution": "internal" },
  453. "production": { "autoIncrement": true }
  454. },
  455. "submit": { "production": { "ios": { "ascAppId": "<APP_STORE_CONNECT_APP_ID>" } } }
  456. }
  457. ```
  458. ```bash
  459. eas build --profile development --platform ios
  460. eas build --profile development --platform android
  461. eas build --profile production --platform ios
  462. eas build --profile production --platform android
  463. eas submit --platform ios
  464. eas submit --platform android
  465. eas metadata:push # push store.config.json (title, subtitle, keywords, description per locale)
  466. ```
  467. ## Important Modules
  468. ### Purchases: StoreKit 2 via expo-iap + RevenueCat observer mode
  469. - `src/lib/purchases.ts`: everything about buying and premium goes through `expo-iap` (`initConnection`, `fetchProducts`, `requestPurchase`, `finishTransaction`, `getActiveSubscriptions`, `getAvailablePurchases`, `restorePurchases`)
  470. - `src/lib/revenuecat.ts`: RevenueCat is configured with `purchasesAreCompletedBy: { type: PURCHASES_ARE_COMPLETED_BY_TYPE.MY_APP, storeKitVersion: STOREKIT_VERSION.STOREKIT_2 }`. It only records purchases (`Purchases.recordPurchase(productId)`) and Apple Ads attribution (`enableAdServicesAttributionTokenCollection()`, no ATT needed). It never decides premium; if RevenueCat is down, purchases still work
  471. - Products: `weekly` + `yearly` subscriptions (same subscription group) and an optional `lifetime` non-consumable
  472. - Premium = an active subscription OR a lifetime purchase. Cache the last value (`premium-cache.ts`) so background tasks can read it without hitting the store
  473. ```ts
  474. // Listen once at startup; renewals, interrupted purchases and Ask to Buy approvals arrive here too.
  475. // Unfinished transactions are re-delivered on every launch.
  476. purchaseUpdatedListener((purchase) => {
  477. if (purchase.purchaseState === 'pending') return notify(purchase); // Ask to Buy: wait for approval
  478. void recordRevenueCatPurchase(purchase.productId) // with a ~5s timeout, before finishing
  479. .then(() => finishTransaction({ purchase, isConsumable: false }))
  480. .finally(() => notify(purchase));
  481. });
  482. // Purchase
  483. requestPurchase({
  484. request: { apple: { sku: productId }, google: { skus: [productId] } },
  485. type: productId === PRODUCT_IDS.LIFETIME ? 'in-app' : 'subs',
  486. });
  487. // Errors come from purchaseErrorListener; ErrorCode.UserCancelled => 'cancelled', not an error alert
  488. ```
  489. - Result type: `'purchased' | 'pending' | 'cancelled' | 'failed'`; only `failed` shows an error alert
  490. - Free trial: show it only if `isEligibleForIntroOfferIOS(subscriptionGroupId)` is true; derive days from `introductoryPricePaymentModeIOS === 'free-trial'` + period
  491. - Add a `.storekit` configuration file to the Xcode scheme to test purchases on the simulator
  492. - RevenueCat attribute `$posthogUserId` = PostHog distinct id, so purchases join analytics users
  493. ### AdMob
  494. - Files: `src/lib/ads.ts` (unit IDs per platform), `src/lib/ads-consent.ts`, `src/context/ads-context.tsx`, `src/components/banner-ad.tsx`
  495. - Ads disabled for premium users and in development (opt in with `EXPO_PUBLIC_ADS_DEV=1`)
  496. - Test IDs must be used in development
  497. ### Onboarding & Paywall Flow (CRITICAL)
  498. Flow: `Onboarding → Permission screens (location?, notifications) → Paywall → Main App (tabs)`
  499. - Each step has a persisted flag in `OnboardingProvider` (`hasCompletedOnboarding`, `hasShownNotificationPermission`, `hasShownPaywall`, ... and `completeX()` setters)
  500. - The root `_layout.tsx` is the single router guard: an effect watches the flags + `useSegments()` and `router.replace`s to the first unfinished step
  501. - Until the current segment matches the expected step, render a loading view instead of the `Stack` (prevents a flash of the tabs)
  502. - Permission screens explain the benefit first, then call the system prompt; "Not now" also completes the step
  503. - The paywall knows it is in the onboarding flow via `!hasShownPaywall`: closing it calls `completePaywall()` + `router.replace('/')`. Opened later (settings, a locked feature) it just does `router.back()`. Pass `?from=settings|feature` for analytics
  504. ```tsx
  505. useEffect(() => {
  506. if (isLoading) return;
  507. const step = segments[0];
  508. if (!hasCompletedOnboarding && step !== 'onboarding') router.replace('/onboarding');
  509. else if (hasCompletedOnboarding && !hasShownNotificationPermission && step !== 'notification-permission')
  510. router.replace('/notification-permission');
  511. else if (hasShownNotificationPermission && !hasShownPaywall && step !== 'paywall') router.replace('/paywall');
  512. }, [isLoading, hasCompletedOnboarding, hasShownNotificationPermission, hasShownPaywall, segments]);
  513. ```
  514. ### Paywall (REQUIRED)
  515. Plans, all with prices from the store (never hardcoded):
  516. 1. **Weekly**
  517. 2. **Yearly** - **selected by default** and highlighted; badge shows the real saving computed from store prices (`1 - yearly.price / (weekly.price * 52)`), and the free trial if eligible
  518. 3. **Lifetime** (optional non-consumable)
  519. ```tsx
  520. const [selectedPlan, setSelectedPlan] = useState<'weekly' | 'yearly' | 'lifetime'>('yearly');
  521. const [plans, setPlans] = useState<Plan[]>([]); // { id, displayPrice, price, currency, trialDays }
  522. useEffect(() => {
  523. getPlans().then(setPlans); // open the page immediately, fill prices when they arrive
  524. }, []);
  525. ```
  526. App Store review (Guideline 3.1.2) requirements - the paywall MUST have:
  527. - A visible close button (and onboarding must continue without buying)
  528. - **Restore Purchases** button
  529. - Price and period for every plan, trial length and what it renews into
  530. - Auto-renewal text ("cancel anytime in App Store settings")
  531. - Tappable **Privacy Policy** and **Terms of Use (EULA)** links (same links in the App Store description)
  532. - After success: `refreshPremiumStatus()` from `useAds()`, then continue the flow / go back
  533. ### Settings Screen Options (REQUIRED)
  534. Settings screen MUST include:
  535. 1. **Language** - Change app language
  536. 2. **Theme** - Light/Dark/System
  537. 3. **Notifications** - Enable/disable notifications
  538. 4. **Remove Ads** - Navigate to paywall (hidden if already premium)
  539. 5. **Restore Purchases**
  540. 6. **Privacy choices** - `showPrivacyOptions()` (only when `privacyOptionsRequired`, EU)
  541. 7. **Analytics** toggle - PostHog opt-in/opt-out (only when analytics is configured)
  542. 8. **Rate / Share / Privacy Policy / Terms / Support** links
  543. 9. **Reset Onboarding** - Restart onboarding flow (`__DEV__` only)
  544. ```tsx
  545. const { isPremium } = useAds();
  546. // Remove Ads - navigates to paywall
  547. const handleRemoveAds = () => {
  548. router.push('/paywall');
  549. };
  550. // Reset onboarding
  551. const handleResetOnboarding = async () => {
  552. await setOnboardingCompleted(false);
  553. router.replace('/onboarding');
  554. };
  555. // In settings list:
  556. {!isPremium && (
  557. <SettingsItem
  558. title={t('settings.removeAds')}
  559. icon="crown.fill"
  560. onPress={handleRemoveAds}
  561. />
  562. )}
  563. <SettingsItem
  564. title={t('settings.resetOnboarding')}
  565. icon="arrow.counterclockwise"
  566. onPress={handleResetOnboarding}
  567. />
  568. ```
  569. ## Localization
  570. - File: `src/lib/i18n.ts`, strings in `src/locales/*.json`
  571. - Initial language: walk `Localization.getLocales()` in order and take the first supported one (a user's second language may be supported), fallback `en`
  572. - Persist the user's choice and load it on startup
  573. - Translate iOS permission texts / app name with `expo.locales` in `app.json` (`{ "tr": "./locales/ios/tr.json" }`) + `CFBundleAllowMixedLocalizations: true`
  574. ### RTL (Arabic, Hebrew, Persian, Urdu)
  575. Switch direction at runtime when the language changes:
  576. ```ts
  577. I18nManager.allowRTL(rtl);
  578. I18nManager.forceRTL(rtl);
  579. if (Platform.OS === 'ios') Settings.set({ AppleLanguages: [lang] }); // native strings, share sheet, alerts
  580. if (I18nManager.isRTL !== rtl) {
  581. // Guard with a stored flag so a failed reload cannot loop
  582. if (__DEV__) DevSettings.reload();
  583. else await Updates.reloadAsync();
  584. }
  585. ```
  586. - Use `start`/`end` (`marginStart`, `paddingEnd`) instead of `left`/`right`
  587. - Flip directional icons (chevrons, arrows) with `transform: [{ scaleX: I18nManager.isRTL ? -1 : 1 }]`
  588. ## Analytics (PostHog)
  589. File: `src/lib/analytics.ts`
  590. ```ts
  591. const posthog = process.env.EXPO_PUBLIC_POSTHOG_KEY
  592. ? new PostHog(process.env.EXPO_PUBLIC_POSTHOG_KEY, {
  593. host: process.env.EXPO_PUBLIC_POSTHOG_HOST ?? 'https://eu.i.posthog.com',
  594. disabled: __DEV__ && process.env.EXPO_PUBLIC_POSTHOG_DEV !== '1',
  595. captureAppLifecycleEvents: true,
  596. errorTracking: { autocapture: { uncaughtExceptions: true, unhandledRejections: true, nativeCrashes: true } },
  597. })
  598. : null;
  599. type Events = {
  600. onboarding_completed: { skipped: boolean };
  601. paywall_viewed: { from: 'onboarding' | 'settings' | 'feature' };
  602. purchase_started: { plan: 'weekly' | 'yearly' | 'lifetime' };
  603. purchase_completed: { plan: 'weekly' | 'yearly' | 'lifetime'; revenue?: number; currency?: string; trial?: boolean };
  604. purchase_failed: { plan: 'weekly' | 'yearly' | 'lifetime'; reason: 'pending' | 'cancelled' | 'failed' };
  605. restore_completed: { active: boolean };
  606. // ...one entry per product event
  607. };
  608. export function track<E extends keyof Events>(event: E, properties: Events[E]) {
  609. posthog?.capture(event, properties);
  610. }
  611. export const trackScreen = (name: string) => void posthog?.screen(name);
  612. ```
  613. - Typed event map - no free-form event names
  614. - Track screens from the root layout: `useEffect(() => trackScreen(pathname), [pathname])`
  615. - Track notification opens with `Notifications.useLastNotificationResponse()` (dedupe by id + date)
  616. - Anonymous only: no PII, no exact coordinates, no user-typed text
  617. - Feature flags (`posthog.getFeatureFlag`) for remote config / A-B tests; always have a default
  618. - Keys live in `.env` (`EXPO_PUBLIC_POSTHOG_KEY`, `EXPO_PUBLIC_POSTHOG_HOST`), never committed
  619. ## Ratings (expo-store-review)
  620. File: `src/lib/rating.ts`
  621. - Ask at a **value moment** (task completed, goal reached), never on launch or after an error
  622. - Conditions: app opened on at least 3 different days, 60+ days since the last request
  623. - Delay ~1.2s so the success animation finishes, check `StoreReview.isAvailableAsync()`, then `StoreReview.requestReview()`
  624. - iOS shows it at most 3 times a year and does not report whether it was shown
  625. - Settings "Rate us" opens `https://apps.apple.com/app/id<ID>?action=write-review` instead
  626. ## Notifications
  627. - Files: `src/lib/notifications.ts`, `src/hooks/use-notifications.ts`
  628. - Remote push needs the `aps-environment` entitlement; local notifications do not
  629. - iOS keeps at most 64 pending local notifications: schedule a rolling window and re-sync on every `AppState` → `active` and from the background task
  630. - Custom sounds: list `.caf` (iOS) / `.wav` files under the `expo-notifications` plugin `sounds` option, refer to them by file name; keep them under 30 s
  631. - Ask permission on the pre-permission screen, not on launch
  632. ## Background Tasks
  633. ```ts
  634. // src/lib/background-sync.ts - imported from app/_layout.tsx so defineTask runs at module load
  635. TaskManager.defineTask(TASK_NAME, async () => {
  636. try {
  637. await syncScheduledContent();
  638. return BackgroundTask.BackgroundTaskResult.Success;
  639. } catch {
  640. return BackgroundTask.BackgroundTaskResult.Failed;
  641. }
  642. });
  643. await BackgroundTask.registerTaskAsync(TASK_NAME, { minimumInterval: 60 }); // minutes, a lower bound only
  644. ```
  645. - Packages: `expo-background-task` + `expo-task-manager`
  646. - iOS decides when it runs (no guarantee); the real refresh happens on foreground, the task is a safety net
  647. - Never touch UI-only APIs (RTL reload, prompts) from a task
  648. ## Widgets & Live Activities (iOS, optional)
  649. - `expo-widgets` + `@expo/ui/swift-ui`: widgets are JSX functions with a `'widget'` directive; they run in the extension, so no hooks, imports or outer constants inside - everything comes from props
  650. - Configure in `app.json` under the `expo-widgets` plugin (`groupIdentifier`, widget `name`, `supportedFamilies`) and use the same App Group in code
  651. - Push data with `Widget.updateTimeline(entries)` (precompute several days of entries so the widget keeps working when the app is not opened)
  652. - Extensions can only read files from the App Group container: copy images there (`Paths.appleSharedContainers[APP_GROUP]`), version the file name when the image changes
  653. - Live Activities (iOS 16.2+) can only be **started** while the app is in the foreground; background tasks may only update a running one
  654. ## Coding Standards
  655. - Use functional components
  656. - Strict TypeScript
  657. - Avoid hardcoded strings
  658. - File names kebab-case (`use-prayer-times.ts`), components PascalCase
  659. - Unit tests for pure logic with `bun test` (`"test": "bun test"`, `@types/bun`)
  660. - Use padding instead of lineHeight
  661. - Use memoization when necessary
  662. ## Context Providers
  663. ```tsx
  664. <ThemeProvider>
  665. <OnboardingProvider>
  666. <AdsProvider>
  667. <Stack />
  668. </AdsProvider>
  669. </OnboardingProvider>
  670. </ThemeProvider>
  671. ```
  672. ## useColorScheme Hook
  673. File: `src/hooks/use-color-scheme.ts`
  674. ```tsx
  675. import { useThemeContext } from '@/context/theme-context';
  676. export function useColorScheme(): 'light' | 'dark' | 'unspecified' {
  677. const { isDark } = useThemeContext();
  678. return isDark ? 'dark' : 'light';
  679. }
  680. ```
  681. ## Important Notes
  682. 1. iOS permissions are defined in `app.json`
  683. 2. Android permissions are defined in `app.json`
  684. 3. New Architecture is the only architecture since SDK 55 - no `newArchEnabled` flag needed
  685. 4. Enable typed routes and the React Compiler via `experiments.typedRoutes` / `experiments.reactCompiler`
  686. 5. Secrets and keys go to `.env` as `EXPO_PUBLIC_*` (and EAS environment variables for builds)
  687. ## App Store & Play Store Notes
  688. - iOS ATT permission required before personalised ads (after the UMP form)
  689. - Restore purchases must work correctly
  690. - Paywall must meet Guideline 3.1.2 (see Paywall section); App Store description must also include the auto-renew text, Privacy Policy and Terms (EULA) links
  691. - Do not request permissions the app does not use (5.1.1); every permission needs a purpose string
  692. - `ITSAppUsesNonExemptEncryption: false` to skip the export compliance question
  693. - Store listing lives in `store.config.json` (EAS Metadata), localized per language
  694. - Target SDK must be up to date
  695. ## Store Screenshots
  696. When the user asks for App Store / Google Play screenshots or store visuals, ALWAYS use the `/app-store-screenshot` skill (invoke it with the Skill tool) instead of building the images by hand.
  697. 1. Take raw screenshots from the simulator (`xcrun simctl io booted screenshot <file>.png`), one per key screen, in every store language
  698. 2. Run `/app-store-screenshot` with those screenshots; it adds the device frame, background and headline while keeping the app UI pixel-exact
  699. 3. Keep the output in `store/screenshots/` next to `store.config.json`
  700. ## Testing Checklist
  701. - UI tested in all languages
  702. - Dark / Light mode
  703. - Notifications
  704. - Premium flow (StoreKit config file on simulator, Sandbox account on device)
  705. - Free trial eligibility, Ask to Buy (pending), cancelled purchase
  706. - Restore purchases
  707. - EU consent form (`EXPO_PUBLIC_ADS_DEBUG_EEA=1`) and ATT prompt
  708. - RTL layout
  709. - Offline support
  710. - Multiple screen sizes
  711. ## After Development
  712. ```bash
  713. npx expo prebuild --clean
  714. bun ios
  715. bun android
  716. ```
  717. > NOTE: `prebuild --clean` recreates ios and android folders. Run it after modifying native modules or app.json.
README.md · README · 65 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Expo Mobile App Skill
  2. A Claude Code skill for building production-ready Expo React Native mobile applications.
  3. ## Features
  4. - **StoreKit 2 (expo-iap)** - Weekly/yearly subscriptions + lifetime purchase, trial eligibility, Ask to Buy
  5. - **RevenueCat (observer mode)** - Purchase records and Apple Ads attribution
  6. - **AdMob** - Banner ads with UMP (GDPR) consent, ATT and premium user detection
  7. - **PostHog** - Typed analytics events, screen tracking, error tracking, feature flags
  8. - **i18n** - Multi-language support with RTL (Turkish/English/Arabic)
  9. - **Onboarding** - Fullscreen video background, permission screens, then paywall
  10. - **Paywall** - Store prices, yearly default, App Store 3.1.2 compliant
  11. - **Ratings** - Native review prompt at value moments
  12. - **Background tasks, widgets & Live Activities** (optional)
  13. - **NativeTabs** - Native tab navigation
  14. - **Theme** - Light/Dark/System mode support
  15. ## Installation
  16. ```bash
  17. npx skills add zaferayan/skills
  18. ```
  19. ## What it does
  20. When you ask Claude Code to create an Expo app, this skill ensures:
  21. 1. **Required Screens**: Onboarding, Paywall, Settings
  22. 2. **Proper Flow**: Onboarding → Paywall → Main App
  23. 3. **Monetization**: StoreKit 2 (expo-iap) + RevenueCat observer + AdMob with consent
  24. 4. **Best Practices**: No AsyncStorage, no lineHeight, NativeTabs only
  25. ## Usage
  26. After installing, simply ask Claude Code:
  27. ```
  28. /zafer-skills Create a water reminder app
  29. ```
  30. Claude will automatically:
  31. - Set up the project structure
  32. - Configure StoreKit purchases, RevenueCat observer mode, AdMob consent and PostHog
  33. - Create onboarding with video background
  34. - Build paywall with subscription options
  35. - Add settings with language, theme, and reset options
  36. ## Tech Stack
  37. - Expo SDK 57 / React Native 0.86
  38. - Expo Router (file-based routing)
  39. - NativeTabs navigation
  40. - expo-iap (StoreKit 2 / Play Billing)
  41. - RevenueCat (react-native-purchases, observer mode)
  42. - AdMob (react-native-google-mobile-ads) + expo-tracking-transparency
  43. - PostHog (posthog-react-native)
  44. - expo-store-review
  45. - i18next + react-i18next
  46. - expo-video
  47. - expo-sqlite (localStorage polyfill)
  48. ## License
  49. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.