docs: wsl setup and expo router skip docs (#130)

williscool · web-flow · commit 7c21aca98dde · 2025-12-24T14:09:15.000-05:00
diff --git a/.cursor/rules/wsl-unison-setup.mdc b/.cursor/rules/wsl-unison-setup.mdc
@@ -10,45 +10,73 @@ This project uses a dual-filesystem setup for development:
 - **Linux/WSL location** (primary development location):
   `/home/william/not_connected_to_windows/CalendarNotification`
 
-- **Windows location** (accessible via WSL at `/mnt/c`):
-  `/mnt/c/Users/william/unison-with-dropbox-symlinked-to-linux/CalendarNotification`
+- **Windows location** (for Android builds - use short path!):
+  - **Short path**: `C:\dev\CN` or `/mnt/c/dev/CN` — BUILD FROM HERE
+  - **Junction for backwards compat**: `C:\Users\william\unison-with-dropbox-symlinked-to-linux\CalendarNotification` → `C:\dev\CN`
 
 ## Sync Strategy
 
-- **Unison** is used to sync files between the Linux and Windows filesystems
-- Most files are synced, but **`node_modules` is NOT synced** due to size
-- `node_modules` is installed separately on each side of the sync
+- **Unison** syncs files between Linux and Windows using profile `non_windows_cnplus.prf`
+- Syncs directly: `/mnt/c/dev/CN` ↔ `/home/william/not_connected_to_windows/CalendarNotification`
+- **`node_modules` is NOT synced** — install separately on each side
+- Run with: `unison non_windows_cnplus`
+
+### ⚠️ CRITICAL: Never sync through the junction!
+
+Unison must point to the **real short path** (`/mnt/c/dev/CN`), NOT the junction path. If you sync through the junction, Unison will replace your Linux directory with a symlink to `/mnt/c/...`, completely defeating the fast-filesystem setup and potentially destroying data.
 
 ## Implications
 
 - When referencing paths, prefer the Linux location (`/home/william/not_connected_to_windows/CalendarNotification`)
-- If `node_modules` appears missing or incomplete, it may need to be installed separately on that side
+- If `node_modules` appears missing or incomplete, run `npm install` on that side
 - Git operations and file system operations are faster on the Linux side
-- Windows Android Studio builds must use the Windows-synced location
-- File system permission issues may occur when accessing Windows files from Linux and vice versus (hence keeping them separate)
+- **Windows Android builds**: Use `C:\dev\CN\android` (short path) to avoid 260-char path limit
+- File system permission issues may occur when accessing Windows files from Linux and vice versa (hence keeping them separate)
 
 ## Windows Long Path Issue (New Architecture)
 
 React Native's New Architecture codegen creates very long file paths that can exceed Windows' 260-character limit. The long project path (`unison-with-dropbox-symlinked-to-linux`) makes this worse.
 
-**Workaround**: Use `subst` to create a short drive letter alias:
+### What Doesn't Work
 
-```cmd
-subst X: "C:\Users\william\unison-with-dropbox-symlinked-to-linux\CalendarNotification"
-```
+- **`subst` drive letter**: Node/Gradle can't properly resolve modules through virtual drives
+- **Junction pointing TO long path**: Build tools "see through" junctions and resolve to the real (long) path
+
+### Solution: Short Path + Junction (December 2024)
+
+Real files live at a short Windows path. Junction at old path provides backwards compatibility:
 
-Then build from `X:\android` instead. This shortens paths significantly and avoids the ninja build errors like:
 ```
-ninja: error: Stat(...): Filename longer than 260 characters
+Real files:     C:\dev\CN  ←── BUILD FROM HERE + UNISON SYNCS HERE
+                   ↑
+         ┌─────────┴─────────┐
+         │                   │
+Junction from old path   Direct access
+(backwards compat only - DO NOT sync through this!)
 ```
 
-**Important**: The `subst` drive is only visible at the same elevation level where it was created. If you run `subst` from a non-Admin command prompt, you must use non-Admin Explorer/terminals to see the `X:` drive. Running as Admin won't see it (and vice versa).
+**Setup (one-time)**:
+```powershell
+# Move files to short path
+Move-Item "C:\Users\william\unison-with-dropbox-symlinked-to-linux\CalendarNotification" "C:\dev\CN"
 
-To remove the substitution later:
-```cmd
-subst X: /d
+# Create junction at old location → short path
+cmd /c mklink /J "C:\Users\william\unison-with-dropbox-symlinked-to-linux\CalendarNotification" "C:\dev\CN"
 ```
 
+**Build from short path**:
+```powershell
+cd C:\dev\CN\android
+.\gradlew assembleDebug
+```
+
+### Separate Issue: React Native 0.81.5 C++ Bug
+
+After fixing paths, you may hit `std::format` compilation errors — this is an RN/NDK bug, not a path issue.
+**Quick fix**: Set `newArchEnabled=false` in `android/gradle.properties`
+
+See full docs: `linuxshared_folder_usage_docs/windows_short_path_for_android_builds.md`
+
 ## NativeWind ESM Issue (Metro on Windows)
 
 NativeWind v4 has a known issue where Metro cannot load the config on Windows due to ESM path handling. This causes errors like:
@@ -66,7 +94,7 @@ Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: Only URLs with a scheme in: file, data,
 
 2. **Build on Windows** (uses pre-built bundle):
    ```powershell
-   cd X:\android
+   cd C:\dev\CN\android
    .\gradlew assembleDebug
    ```
 
diff --git a/docs/dev_todo/expo_router_migration.md b/docs/dev_todo/expo_router_migration.md
@@ -1,102 +1,59 @@
 # Expo Router Migration
 
-## Status: Blocked - Awaiting React Native Upgrade
+## Status: Evaluated & Intentionally Deferred
 
-## Summary
+## Decision (December 2025)
 
-Attempted migration to Expo Router v3 for file-based routing but encountered compatibility issues with the current bare React Native 0.74.5 setup.
+After upgrading to React Native 0.81.5 and Expo SDK 54 (which removed the original blockers), we re-evaluated Expo Router and decided **not to migrate**.
 
-## Current Setup (Working)
+### Why We're Skipping It
 
-- **React Native**: 0.74.5
-- **Expo SDK**: 51
+| Factor | Assessment |
+|--------|------------|
+| **App complexity** | Only 3 screens (Home, Settings, SyncDebug) |
+| **Navigation needs** | Simple stack - no nested routes, tabs, or drawers |
+| **Deep linking** | Not needed for a sync settings UI |
+| **Web support** | Android-only app |
+| **Current solution** | React Navigation works perfectly fine |
+
+### Cost vs Benefit
+
+**Costs of migrating:**
+- Additional dependencies (`expo-router`, `expo-linking`, `expo-constants`, `@expo/metro-runtime`)
+- More complex Metro/Babel configuration
+- Migration effort (~2-4 hours)
+- Previous attempt had `require.context` issues in bare RN
+
+**Benefits:**
+- File-based routing (marginal - we only have 3 screens)
+- Automatic deep links (not needed)
+- Slightly less boilerplate (trade ~50 lines in `index.tsx` for `_layout.tsx`)
+
+**Verdict:** Over-engineering for a 3-screen settings UI.
+
+## Current Setup (Working Well)
+
+- **React Native**: 0.81.5
+- **Expo SDK**: 54
 - **Navigation**: React Navigation (`@react-navigation/native-stack`)
-- **UI Components**: Gluestack UI v1
-- **Styling**: NativeWind v2 (Tailwind for RN)
+- **UI Components**: Gluestack UI v2
+- **Styling**: NativeWind v4
 - **Entry Point**: `index.tsx` with explicit screen imports
+- **Screens**: `app/index.tsx`, `app/settings.tsx`, `app/sync-debug.tsx`
+
+## When to Reconsider
+
+Expo Router would make sense if the app grows to include:
+- 10+ screens with complex navigation flows
+- Nested navigators (tabs within stacks, drawers, etc.)
+- Web support requirements
+- Deep linking for sharing specific screens
+
+## Historical Context
+
+Originally blocked on RN 0.74.5 / Expo 51 due to:
+- `require.context` failures in bare RN
+- Dependency version conflicts with expo-module-gradle-plugin
+- NativeWind v4 / react-native-worklets incompatibilities
 
-## Target Versions for Original Goals
-
-| Package | Current | Target | Why |
-|---------|---------|--------|-----|
-| **React Native** | 0.74.5 | **0.76.x** | New Architecture required for worklets |
-| **Expo SDK** | 51 | **52** | Expo Router v4 + updated gradle plugins |
-| **Expo Router** | ❌ removed | **~4.x** | Better bare RN support in v4 |
-| **NativeWind** | 2.x | **4.x** | Requires RN 0.76+ for worklets |
-| **react-native-svg** | 15.2.0 (broken) | **15.x** | Compatible with RN 0.76+ |
-
-### Upgrade Helper
-
-Use this link to see all required changes:
-https://react-native-community.github.io/upgrade-helper/?from=0.74.5&to=0.76.0
-
-## What We Tried
-
-### Expo Router v3
-- File-based routing in `app/` directory
-- `require.context` for auto-discovery of routes
-- `ExpoRoot` component as entry point
-
-### NativeWind v4
-- Direct Tailwind CSS integration
-- `withNativeWind` Metro wrapper
-
-## Issues Encountered
-
-### 1. `require.context` Failure
-Expo Router uses `require.context('./app')` to auto-discover route files. This relies on Metro's experimental features that didn't work in this bare RN setup - `ExpoRoot` couldn't find any routes, resulting in blank screens.
-
-### 2. Dependency Version Conflicts
-- `expo-router@~3.5.x` → `expo-linking@~6.3.x` → expected newer gradle plugin infrastructure
-- `expo-module-gradle-plugin` version mismatches between Expo SDK 51 packages
-- `react-native-svg@15.x` incompatible with RN 0.74.5 (downgraded to 13.x)
-
-### 3. NativeWind v4 Incompatibilities
-- Required `tailwindcss@3.x` (v4 not supported)
-- `react-native-worklets` incompatible with RN 0.74.5
-- `lightningcss` platform-specific binaries failed in Windows/WSL environment
-
-### 4. Windows/WSL Environment
-- Separate `node_modules` on Windows and Linux due to file sync
-- Native binary dependencies (like `lightningcss`) need platform-specific builds
-
-## Migration Checklist
-
-### Prerequisites
-- [ ] Upgrade to React Native 0.76.x
-- [ ] Upgrade to Expo SDK 52
-- [ ] Verify New Architecture is enabled
-- [ ] Clean rebuild on Windows (`.\gradlew clean`)
-
-### Migration Steps
-1. [ ] Add `expo-router@~4.x` and `expo-linking`
-2. [ ] Update `package.json` main to `"expo-router/entry"`
-3. [ ] Update `app.json` with expo-router plugin
-4. [ ] Recreate `app/_layout.tsx` with providers
-5. [ ] Update screen files to use `useRouter()` instead of `useNavigation()`
-6. [ ] Add NativeWind v4 + tailwindcss v3
-7. [ ] Update `metro.config.js` with `withNativeWind`
-8. [ ] Test on Windows/WSL environment
-9. [ ] Remove React Navigation packages
-
-## Files to Reuse
-
-These files were created and can be adapted:
-
-| File | Status | Notes |
-|------|--------|-------|
-| `app/index.tsx` | ✅ Working | Update imports for expo-router |
-| `app/settings.tsx` | ✅ Working | Update imports for expo-router |
-| `app/sync-debug.tsx` | ✅ Working | No navigation changes needed |
-| `lib/components/ui/` | ✅ Working | Keep as-is |
-| `lib/theme/colors.ts` | ✅ Working | Keep as-is |
-| `lib/navigation/types.ts` | ⚠️ Remove | Not needed with expo-router |
-| `app/_layout.tsx` | ❌ Deleted | Recreate with expo-router imports |
-
-## References
-
-- [Expo Router Docs](https://docs.expo.dev/router/introduction/)
-- [NativeWind v4 Docs](https://www.nativewind.dev/)
-- [React Native Upgrade Helper](https://react-native-community.github.io/upgrade-helper/?from=0.74.5&to=0.76.0)
-- [Expo SDK 52 Release Notes](https://expo.dev/changelog)
-- [React Native 0.76 Release](https://reactnative.dev/blog)
+These blockers were resolved by upgrading to RN 0.81.5 / Expo 54, but the migration was deemed unnecessary for the app's scope.
