expo-file-system-bundled-pr-verification

This repository demonstrates and validates the documentation updates proposed in Expo PR #41272.

The guide below explains how to clone this example repo, run it on Android/iOS, and verify both methods of accessing files:

1. Using expo-asset (Recommended)
2. Using Paths.bundle (Advanced / Native-only)

---

1. Clone & Install

git clone https://github.com/dileepapeiris/expo-file-system-bundled-pr-verification.git
cd expo-file-system-bundled-pr-verification
npm install

---

2. Generate Native Projects

Before adding custom assets to the native bundles, we must generate the native folders (android and ios).

npx expo prebuild

Note: We run this before the setup below. If you run prebuild again later, it may overwrite the manual changes made in the next steps (specifically the iOS Xcode configuration).

---

3. Prepare Native Projects (Required for Paths.bundle)

The Paths.bundle example will NOT work unless example.txt is manually added into the native bundle. Expo does not automatically copy JS project files into the native bundle structure.

Android Setup

Goal: Place the file in android/app/src/main/assets/.

1. If the assets folder does not exist, create it:

   mkdir -p android/app/src/main/assets

2. Copy the example file:

   cp exampleFile/example.txt android/app/src/main/assets/

iOS Setup

Goal: Add the file to the "Copy Bundle Resources" build phase in Xcode.

1. Open the iOS project workspace:

   xed ios

2. In Xcode:

   1. Go to the Project Navigator (left sidebar).
   2. Select YourApp (the root node).
   3. Select the Target (YourApp).
   4. Go to the Build Phases tab.
   5. Expand Copy Bundle Resources.
   6. Drag example.txt (from Finder) into this list.
   7. Ensure "Copy items if needed" is checked if prompted.

This ensures the file becomes part of the raw iOS Main Bundle.

---

4. Running the Example App

Now that the native files are in place, run the app.

Android

npx expo run:android

iOS

npx expo run:ios

---

5. What You Can Test

The app contains two tabs (or buttons) corresponding to the two methods below.

Method 1: expo-asset (Recommended)

This works automatically with files inside your JavaScript project structure. No native file placement is needed.

Code Example:

import { Asset } from 'expo-asset';
import { File } from 'expo-file-system';

const doSomethingWithAsset = async () => {
  // 1. Resolve asset from JS
  const asset = Asset.fromModule(require('./assets/images/icon.png'));
  
  // 2. Ensure downloaded
  await asset.downloadAsync();
  
  // 3. Read
  const file = new File(asset.localUri!);
  const content = await file.text();
  console.log(content);
};

Expected Behavior:

• Android: Loads normally.
• iOS: Loads normally.
• Source: Uses the JS-included assets folder.

Method 2: Paths.bundle (Advanced / Native Only)

This allows access to files explicitly added to the platform's native bundle (the steps you performed in Section 3).

Code Example:

import { File, Paths } from 'expo-file-system';
import { Platform } from 'react-native';

const readNativeBundle = async () => {
  const fileName = 'example.txt';
  
  // 1. Point to native bundle location
  const bundleFile = new File(Paths.bundleDirectory, fileName);

  if (!bundleFile.exists) {
    console.warn('File not found in native bundle');
    return;
  }

  let fileToRead = bundleFile;

  // 2. iOS Specific Handling (Bundle is Read-Only)
  if (Platform.OS === 'ios') {
    const documentFile = new File(Paths.document, fileName);
    // Must copy to document directory before reading
    await bundleFile.copy(documentFile);
    fileToRead = documentFile;
  }

  const content = await fileToRead.text();
  console.log(content);
};

Expected Behavior:

• Android: Can read directly from android/app/src/main/assets/. bundleDirectory resolves correctly.
• iOS: Paths.bundleDirectory points to the Main Bundle (read-only). The app logs a copy operation to Paths.document, then reads the file successfully.

---

6. Screen Recordings

The following table demonstrates the expected output for both methods on both platforms.

Feature	Android	iOS
Normal Assets (expo-asset)	Screen.Recording.2025-11-29.at.18.58.39.mov	Simulator.Screen.Recording.-.iPhone.16.Plus.-.2025-11-29.at.19.03.35.mov
Bundle Path (Paths.bundle)	Screen.Recording.2025-11-29.at.18.59.48.mov	Simulator.Screen.Recording.-.iPhone.16.Plus.-.2025-11-29.at.19.04.50.mov

---

7. Verification Checklist

If the documentation and implementation are correct, you should see:

• expo-asset Tab: Content loads correctly using Asset.fromModule(require(...)).
• Paths.bundle Tab (Android): Reads file directly from native assets.
• Paths.bundle Tab (iOS): Successfully copies the file from the bundle to documents, then reads it.

Conclusion

This setup validates:

1. The difference between JS-based assets (expo-asset) and native bundle assets.
2. Why bundleDirectory does not point to standard JS assets.
3. How to properly use Paths.bundle when working with files inside the native project structure.