create-react-native-airborne 0.0.1

package/template/Justfile

@@ -0,0 +1,48 @@
+set shell := ["zsh", "-cu"]
+
+install:
+  bun install --workspaces
+
+fmt:
+  bunx prettier --write client server
+
+prebuild:
+  cd client && bunx expo prebuild --platform all
+
+dev:
+  bunx concurrently -n CLIENT,SERVER -c blue,green "just dev-client" "just dev-server"
+
+dev-client:
+  cd client && bun run start
+
+dev-server:
+  cd server && bun run dev
+
+ios:
+  cd client && bun run ios
+
+android:
+  cd client && bun run android
+
+lint:
+  cd client && bun run lint
+  cd server && bun run lint
+
+typecheck:
+  cd client && bun run typecheck
+  cd server && bun run typecheck
+
+test:
+  cd client && bun run test
+  cd server && bun run test
+
+test-client:
+  cd client && bun run test
+
+test-server:
+  cd server && bun run test
+
+ci:
+  just lint
+  just typecheck
+  just test

package/template/README.md

@@ -0,0 +1,94 @@
+# React Native Airborne
+
+Opinionated React Native starter for mobile-first apps with Expo + Convex.
+
+## 🧰 Stack
+
+- Bun workspaces monorepo (`client/`, `server/`)
+- Expo + Expo Router + Native Tabs (SDK 55)
+- Uniwind + Tailwind v4
+- Clerk authentication
+- Convex backend + `convex-test`
+- Zustand + MMKV persistence
+- Expo push notifications
+
+## 🤝 Contributor Guide
+
+Detailed implementation and maintenance notes for engineers/agents live in `AGENTS.md`.
+
+## ✅ Prerequisites
+
+- Bun `1.3.4+`
+- `just` command runner
+- Expo toolchain for iOS/Android simulators
+- Clerk app + Convex project
+
+## ⚡ Quickstart
+
+```bash
+bun install --workspaces
+cp client/.env.example client/.env
+cp server/.env.example server/.env
+```
+
+First-time Convex setup (one-time per new deployment):
+
+```bash
+cd server
+bun run dev
+```
+
+Then run both apps:
+
+```bash
+just dev
+```
+
+## 🧪 Commands
+
+- `just dev`: start Expo + Convex
+- `just dev-client`: start Expo only
+- `just dev-server`: start Convex only
+- `just fmt`: run Prettier on client and server
+- `just prebuild`: generate local iOS/Android native folders
+- `just ios`: launch iOS app
+- `just android`: launch Android app
+- `just lint`: lint/type lint checks
+- `just typecheck`: TypeScript checks
+- `just test`: client + server tests
+- `just test-client`: client tests only
+- `just test-server`: server tests only
+- `just ci`: lint + typecheck + tests
+
+## 📱 Native Projects
+
+Generate native projects locally when needed:
+
+```bash
+just prebuild
+```
+
+`client/ios` and `client/android` are intentionally gitignored and should not be committed.
+
+## 🔐 Environment Variables
+
+### Client (`client/.env`)
+
+- `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY`
+- `EXPO_PUBLIC_CONVEX_URL`
+- `EXPO_PUBLIC_EAS_PROJECT_ID` (optional)
+
+### Server (`server/.env`)
+
+- `CLERK_JWT_ISSUER_DOMAIN`
+- `EXPO_PUSH_ENDPOINT` (optional)
+- `EXPO_ACCESS_TOKEN` (optional)
+
+## 📝 Notes
+
+- Mobile-only target (iOS/Android).
+- Do not store sensitive auth tokens in MMKV.
+- Uniwind classes are enabled by `client/global.css` and `client/metro.config.js`.
+- `SafeAreaView` is wrapped with `withUniwind` in `client/src/components/screen.tsx` for className support.
+- `server/convex/_generated` ships with starter stubs so typecheck/tests pass before deployment setup.
+  After connecting Convex, run `cd server && bun run codegen` to regenerate.

package/template/client/.env.example

@@ -0,0 +1,3 @@
+EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=
+EXPO_PUBLIC_CONVEX_URL=
+EXPO_PUBLIC_EAS_PROJECT_ID=

package/template/client/.vscode/extensions.json

@@ -0,0 +1 @@
+{ "recommendations": ["expo.vscode-expo-tools"] }

package/template/client/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+  "editor.codeActionsOnSave": {
+    "source.fixAll": "explicit",
+    "source.organizeImports": "explicit",
+    "source.sortMembers": "explicit"
+  }
+}

package/template/client/README.md

@@ -0,0 +1,33 @@
+# Airborne Client
+
+Expo Router app configured for:
+
+- Clerk authentication
+- Convex client integration
+- Uniwind (Tailwind v4)
+- Zustand + MMKV local state persistence
+- Expo push notifications
+
+## Run
+
+```bash
+bun install
+bun run start
+```
+
+Generate native folders locally when you need native runs:
+
+```bash
+bunx expo prebuild --platform all
+```
+
+Then use:
+
+- `bun run ios`
+- `bun run android`
+
+## Required env (`.env`)
+
+- `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY`
+- `EXPO_PUBLIC_CONVEX_URL`
+- `EXPO_PUBLIC_EAS_PROJECT_ID` (optional)

package/template/client/app/(app)/_layout.tsx

@@ -0,0 +1,34 @@
+import { useAuth } from "@clerk/clerk-expo";
+import { Redirect } from "expo-router";
+import { NativeTabs } from "expo-router/unstable-native-tabs";
+
+export default function AppLayout() {
+  const { isLoaded, isSignedIn } = useAuth();
+
+  if (!isLoaded) {
+    return null;
+  }
+
+  if (!isSignedIn) {
+    return <Redirect href="/(auth)/sign-in" />;
+  }
+
+  return (
+    <NativeTabs>
+      <NativeTabs.Trigger name="index" disableTransparentOnScrollEdge>
+        <NativeTabs.Trigger.Icon sf={{ default: "house", selected: "house.fill" }} md="home" />
+        <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
+      </NativeTabs.Trigger>
+
+      <NativeTabs.Trigger name="push" disableTransparentOnScrollEdge>
+        <NativeTabs.Trigger.Icon sf={{ default: "bell", selected: "bell.fill" }} md="notifications" />
+        <NativeTabs.Trigger.Label>Push</NativeTabs.Trigger.Label>
+      </NativeTabs.Trigger>
+
+      <NativeTabs.Trigger name="settings" disableTransparentOnScrollEdge>
+        <NativeTabs.Trigger.Icon sf="gearshape" md="settings" />
+        <NativeTabs.Trigger.Label>Settings</NativeTabs.Trigger.Label>
+      </NativeTabs.Trigger>
+    </NativeTabs>
+  );
+}

package/template/client/app/(app)/index.tsx

@@ -0,0 +1,66 @@
+import { SignedIn, useUser } from "@clerk/clerk-expo";
+import { useMutation, useQuery } from "convex/react";
+import { Link } from "expo-router";
+import { useEffect, useRef } from "react";
+import { Text, View } from "react-native";
+import { Screen } from "@/src/components/screen";
+import { SignOutButton } from "@/src/components/sign-out-button";
+import { api } from "@convex/_generated/api";
+
+export default function HomeScreen() {
+  const { user } = useUser();
+  const currentUser = useQuery(api.users.current, {});
+  const bootstrapUser = useMutation(api.users.bootstrap);
+  const didBootstrap = useRef(false);
+
+  useEffect(() => {
+    if (!user || currentUser !== null || didBootstrap.current) {
+      return;
+    }
+
+    didBootstrap.current = true;
+    void bootstrapUser({
+      email: user.primaryEmailAddress?.emailAddress,
+      name: user.fullName ?? undefined,
+      imageUrl: user.imageUrl ?? undefined,
+    });
+  }, [bootstrapUser, currentUser, user]);
+
+  return (
+    <Screen>
+      <SignedIn>
+        <View className="flex-1 gap-5">
+          <View className="gap-2">
+            <Text className="text-3xl font-bold text-zinc-900 dark:text-zinc-100">
+              React Native Airborne
+            </Text>
+            <Text className="text-zinc-600 dark:text-zinc-300">
+              Opinionated Expo + Convex + Clerk starter with Uniwind.
+            </Text>
+          </View>
+
+          <View className="rounded-xl border border-zinc-300 bg-zinc-50 p-4 dark:border-zinc-800 dark:bg-zinc-900">
+            <Text className="text-sm text-zinc-600 dark:text-zinc-300">Authenticated user</Text>
+            <Text className="text-base font-semibold text-zinc-900 dark:text-zinc-100">
+              {currentUser?.email ?? "Loading profile..."}
+            </Text>
+            <Text className="text-sm text-zinc-500 dark:text-zinc-400">
+              Clerk ID: {currentUser?.clerkUserId ?? "..."}
+            </Text>
+          </View>
+
+          <View className="gap-3">
+            <Link href="/(app)/settings" className="text-base font-medium text-blue-600">
+              Open Settings (theme)
+            </Link>
+            <Link href="/(app)/push" className="text-base font-medium text-blue-600">
+              Open Push Demo
+            </Link>
+          </View>
+
+          <SignOutButton />
+        </View>
+      </SignedIn>
+    </Screen>
+  );
+}

package/template/client/app/(app)/push.tsx

@@ -0,0 +1,75 @@
+import { useAction, useMutation } from "convex/react";
+import { useState } from "react";
+import { Platform, Text, View } from "react-native";
+import { PrimaryButton } from "@/src/components/primary-button";
+import { Screen } from "@/src/components/screen";
+import { registerForPushNotificationsAsync } from "@/src/lib/notifications";
+import { usePreferencesStore } from "@/src/store/preferences-store";
+import { api } from "@convex/_generated/api";
+
+export default function PushScreen() {
+  const [status, setStatus] = useState<string>("Idle");
+  const lastPushToken = usePreferencesStore((state) => state.lastPushToken);
+  const setLastPushToken = usePreferencesStore((state) => state.setLastPushToken);
+
+  const registerToken = useMutation(api.push.registerToken);
+  const unregisterToken = useMutation(api.push.unregisterToken);
+  const sendTestNotification = useAction(api.push.sendTestNotification);
+
+  const onRegister = async () => {
+    try {
+      setStatus("Requesting notification permissions...");
+      const token = await registerForPushNotificationsAsync();
+      setStatus("Registering token in Convex...");
+      await registerToken({ token, platform: Platform.OS === "ios" ? "ios" : "android" });
+      setLastPushToken(token);
+      setStatus("Token registered.");
+    } catch (error) {
+      setStatus(error instanceof Error ? error.message : "Failed to register push token.");
+    }
+  };
+
+  const onSendTest = async () => {
+    try {
+      setStatus("Sending test notification...");
+      const response = await sendTestNotification({});
+      setStatus(`Sent. Status ${response.status}.`);
+    } catch (error) {
+      setStatus(error instanceof Error ? error.message : "Failed to send notification.");
+    }
+  };
+
+  const onUnregister = async () => {
+    if (!lastPushToken) {
+      setStatus("No token stored to remove.");
+      return;
+    }
+
+    try {
+      await unregisterToken({ token: lastPushToken });
+      setLastPushToken(null);
+      setStatus("Token removed.");
+    } catch (error) {
+      setStatus(error instanceof Error ? error.message : "Failed to remove token.");
+    }
+  };
+
+  return (
+    <Screen>
+      <View className="flex-1 gap-4">
+        <Text className="text-2xl font-bold text-zinc-900 dark:text-zinc-100">Push Demo</Text>
+
+        <Text className="text-sm text-zinc-600 dark:text-zinc-300">Status: {status}</Text>
+        <Text className="text-xs text-zinc-500 dark:text-zinc-400">
+          Last token: {lastPushToken ?? "Not registered yet"}
+        </Text>
+
+        <View className="gap-3">
+          <PrimaryButton onPress={onRegister}>Register push token</PrimaryButton>
+          <PrimaryButton onPress={onSendTest}>Send test notification</PrimaryButton>
+          <PrimaryButton onPress={onUnregister}>Remove token</PrimaryButton>
+        </View>
+      </View>
+    </Screen>
+  );
+}

package/template/client/app/(app)/settings.tsx

@@ -0,0 +1,36 @@
+import { useUniwind } from "uniwind";
+import { Text, View } from "react-native";
+import { PrimaryButton } from "@/src/components/primary-button";
+import { Screen } from "@/src/components/screen";
+import { usePreferencesStore } from "@/src/store/preferences-store";
+import type { ThemePreference } from "@/src/types/theme";
+
+export default function SettingsScreen() {
+  const { theme, hasAdaptiveThemes } = useUniwind();
+  const selectedTheme = usePreferencesStore((state) => state.theme);
+  const setTheme = usePreferencesStore((state) => state.setTheme);
+
+  const activeTheme = hasAdaptiveThemes ? "system" : theme;
+
+  const onChangeTheme = (nextTheme: ThemePreference) => {
+    setTheme(nextTheme);
+  };
+
+  return (
+    <Screen>
+      <View className="flex-1 gap-4">
+        <Text className="text-2xl font-bold text-zinc-900 dark:text-zinc-100">Settings</Text>
+
+        <Text className="text-sm text-zinc-600 dark:text-zinc-300">
+          Active theme: {activeTheme}. Stored preference: {selectedTheme}.
+        </Text>
+
+        <View className="gap-3">
+          <PrimaryButton onPress={() => onChangeTheme("system")}>Use system theme</PrimaryButton>
+          <PrimaryButton onPress={() => onChangeTheme("light")}>Use light theme</PrimaryButton>
+          <PrimaryButton onPress={() => onChangeTheme("dark")}>Use dark theme</PrimaryButton>
+        </View>
+      </View>
+    </Screen>
+  );
+}

package/template/client/app/(auth)/_layout.tsx

@@ -0,0 +1,22 @@
+import { useAuth } from "@clerk/clerk-expo";
+import { Redirect, Stack } from "expo-router";
+
+export default function AuthLayout() {
+  const { isLoaded, isSignedIn } = useAuth();
+
+  if (!isLoaded) {
+    return null;
+  }
+
+  if (isSignedIn) {
+    return <Redirect href="/" />;
+  }
+
+  return (
+    <Stack
+      screenOptions={{
+        headerShown: false,
+      }}
+    />
+  );
+}