> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Add an Expo mobile app to a Forge backend

> Scaffold an Expo React Native app beside your Forge API, call it through the same generated React Query hooks the web frontend uses, and bundle it.

By the end of this guide your Forge project has a second frontend, an Expo React Native app in `frontends/mobile`, with a screen that lists products from your API. It does not get a hand-written client: `forge generate` writes the same typed hooks into it that the web frontend uses, from the same proto, so a new RPC reaches both apps on the next generate.

## Before you begin

* A Forge Go project with an entity: [Build a Go and React app](https://docs.reliantlabs.io/guides/forge/build-go-react-app-connect-rpc.md). The examples use its `CatalogService` and `Product`.
* Node.js and npm. To run the app on a phone, the Expo Go app or an emulator.
* Forge v1.6.1 or later in the project (`reliant forge --version`).

**1. Scaffold the app**

```bash terminal theme={null}
reliant forge scaffold frontend mobile --kind mobile
```

```text Output (trimmed) theme={null}
✅ Code generation complete — 71 file(s) written, 24 changed (11 new, 13 updated).

✅ Frontend 'mobile' added successfully!
```

The scaffold installs the app's dependencies and ends with a `forge generate`. What it wrote:

| Path | What it is |
| - | - |
| `frontends/mobile/app/` | Screens, routed by expo-router: `_layout.tsx` and `index.tsx` |
| `frontends/mobile/src/hooks/catalog-service-hooks_gen.ts` | `useListProducts`, `useCreateProduct` and the rest, the same file the web frontend has |
| `frontends/mobile/src/lib/connect.ts` | The Connect transport, with the same interceptors as the web frontends (trace propagation, typed errors) |
| `frontends/mobile/src/lib/auth/` | The sign-in seam, holding a mock session provider |

**2. Point TypeScript and Metro at the generated code**

The generated protobuf code imports its neighbours as `./x_pb.js`, and the hooks import `@reliantlabs/forge-web-runtime/service-hooks` through the package's exports map. Expo's defaults resolve neither, so give the app two settings. In `frontends/mobile/tsconfig.json`, add to `compilerOptions`:

```json frontends/mobile/tsconfig.json theme={null}
"moduleResolution": "bundler",
"module": "esnext"
```

And in `frontends/mobile/metro.config.js`, just above `module.exports = config;`:

```js frontends/mobile/metro.config.js theme={null}
// Generated protobuf code imports "./x_pb.js"; the file on disk is x_pb.ts.
config.resolver.resolveRequest = (context, moduleName, platform) => {
  if (moduleName.startsWith(".") && moduleName.endsWith(".js")) {
    try {
      return context.resolveRequest(context, moduleName.slice(0, -3), platform);
    } catch {}
  }
  return context.resolveRequest(context, moduleName, platform);
};
```

**3. Call the API from a screen**

Replace the placeholder screen with a product list:

```tsx frontends/mobile/app/index.tsx theme={null}
import { FlatList, StyleSheet, Text, View } from "react-native";
import { useListProducts } from "../src/hooks";

export default function ProductsScreen() {
  const { data, error, isPending } = useListProducts({});

  if (isPending) return <Text style={styles.message}>Loading…</Text>;
  if (error) return <Text style={styles.message}>{error.message}</Text>;

  return (
    <FlatList
      data={data.products}
      keyExtractor={(p) => p.id}
      renderItem={({ item }) => (
        <View style={styles.row}>
          <Text style={styles.name}>{item.name}</Text>
          <Text>{(Number(item.priceCents) / 100).toFixed(2)}</Text>
        </View>
      )}
    />
  );
}

const styles = StyleSheet.create({
  message: { padding: 24 },
  row: { flexDirection: "row", justifyContent: "space-between", padding: 16 },
  name: { fontWeight: "600" },
});
```

The hook is an ordinary TanStack Query hook, so `data` is typed as `ListProductsResponse`, and `useCreateProduct` invalidates this list when a product is added.

**4. Check that it typechecks and bundles**

```bash terminal theme={null}
cd frontends/mobile
npm run typecheck
npx expo export --platform android
```

```text Output (trimmed) theme={null}
> mobile@0.1.0 typecheck
> tsc --noEmit

› android bundles (1):
_expo/static/js/android/entry-d78d7c69442ebe4d24d166a8c7cc499e.hbc (3.54 MB)

Exported: dist
```

A typecheck with no errors and an exported bundle mean every generated import resolves in the app's bundler, not only in your editor.

**5. Run it against your dev API**

Start the API with `reliant forge env up dev` and note its URL (`api  http://localhost:8085` in the summary). On a phone or emulator, `localhost` is the device itself, so point the app at an address the device can reach, such as your computer's LAN address, and start Expo's dev server from the app's directory:

```bash terminal theme={null}
EXPO_PUBLIC_API_URL=http://192.168.1.20:8085 npx expo start
```

Scan the QR code with Expo Go. Every RPC requires sign-in by default, and the app sends no credentials yet, so the screen shows an `unauthenticated` error (`missing Authorization header`) until you wire a sign-in (below).

**6. Keep the app out of hosted deploys**

The scaffold also adds the app to the staging and prod bundles in `deploy/kcl/staging/main.k` and `deploy/kcl/prod/main.k`. Reliant hosting serves web frontends; it does not build or serve a native app. Delete these lines from both files:

```kcl deploy/kcl/prod/main.k theme={null}
    frontends += [
        _hosted_frontend(_mobile_frontend)
    ]
```

Then check that the env declares only your web frontend:

```bash terminal theme={null}
reliant forge env render prod
```

```text Output (trimmed) theme={null}
[render] prod — 4 object(s) of 0 rendered
  web (static)
  shop (database)
```

## What this does not do

* **It does not ship the app to phones.** Reliant hosting does not build, sign, host or distribute iOS or Android apps. Build and submit them with Expo's own tools (EAS Build and Submit) or Xcode and Android Studio.
* **It does not sign users in.** The scaffold ships a mock session provider, so the app attaches no token. Implement `AuthProvider` in `src/lib/auth/provider.ts` over your identity source, then call `setAuthTokenGetter(() => provider.getToken())` in `app/_layout.tsx`, as the comment there shows. Until then, only RPCs with `auth_required: false` answer the app.
* **It does not design the app.** The scaffolded screen is a placeholder.

## Troubleshooting

> [accordion] Cannot find module '@reliantlabs/forge-web-runtime/service-hooks' or its corresponding type declarations
>
> `npm run typecheck` is resolving with Expo's default `moduleResolution: node`. Add the two `compilerOptions` from the second step.

> [accordion] None of these files exist: \* src/gen/forge/v1/forge\_pb.js
>
> Metro cannot map the generated `.js` import to the `.ts` file. Add the `resolveRequest` function from the second step to `metro.config.js`, then restart `expo start`.

> [accordion] frontend\_mobile.log: npm error Missing script: "dev"
>
> `env up dev` tries to start the app with `npm run dev`, which an Expo app does not have. The API is unaffected. Start the app yourself with `npx expo start` from `frontends/mobile`.

## Next steps

> [card] [Add a custom RPC](https://docs.reliantlabs.io/guides/forge/add-custom-rpc.md)
>
> Add an RPC; its hook appears in both frontends on the next generate.

> [card] [Add sign-in with passkeys](https://docs.reliantlabs.io/guides/forge/add-sign-in-passkeys.md)
>
> Set up the identity your mobile sign-in will use.

> [card] [Build the UI before the backend](https://docs.reliantlabs.io/guides/forge/build-ui-before-backend-mock-mode.md)
>
> Work on screens against mock data.

> [card] [Adding features](https://docs.reliantlabs.io/forge/adding-features.md)
>
> Every scaffold forge offers, frontends included.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.