expo-tv-config

Files (1)

• SKILL.md

SKILL.md (first lines)

# Expo TV configuration

> The Expo plugin `@react-native-tvos/config-tv` is the single switch that makes an Expo app build for TV. Get this wrong and you ship a phone app to a TV launcher. Get it right and most platform-specific config is automatic.

## The one environment variable that matters

```bash
EXPO_TV=1
```

This **must** be set when:
- Running `expo prebuild`
- Running `expo run:android` or `expo run:ios` for a TV build
- Running EAS Build for a TV profile

For harness-driven Android work, prefer `expo prebuild` followed by the Gradle
wrapper and `android run`. Treat `expo run:android` as a manual compatibility
command because Android CLI should own deployment and launch when available.

Without it, the plugin no-ops and you get a mobile build. The `expo_prebuild` tool always sets it; if a user invokes prebuild manually, the symptom is silent — the build succeeds but the app is wrong.

A handy `.envrc` (direnv) or shell alias avoids forgetting:
```bash
export EXPO_TV=1
```

## Plugin options

```json
[
  "@react-native-tvos/config-tv",
  {
    "isTV": true,
    "androidTVBanner": "./assets/icon-400x240.png",
    "showVerboseWarnings": false
  }
]
```

- `isTV: true` — required. Drives Android leanback config and tvOS deployment target.
- `androidTVBanner` — path to the 400×240 banner. Required for Android TV / Fire TV. See `firetv-leanback.md`.
- `showVerboseWarnings` — verbose prebuild output. Useful when debugging.

## What the plugin does (so you know what NOT to do manually)

On Android:
- Adds `<intent-filter>` with `LEANBACK_LAUNCHER` to the main activity
- Adds `<uses-feature android:name="android.software.leanback" android:required="false" />`
- Adds `<uses-feature android:name="android.hardware.touchscreen" android:required="false" />`
- References the banner in the application tag

On iOS:
- Sets deployment target to tvOS
- Switches the Xcode target to Apple TV
- Adjusts Info.plist for TV (removes phone-only keys)

**This is why you don't edit native files directly.** Anything the plugin does, the plugin owns. Manual edits get clobbered on the next prebuild.

## Prebuild — when and why

```bash
EXPO_TV=1 npx expo prebuild --clean
```

`--clean` regenerates `ios/` and `android/` from scratch. This is what you want in CI and in the harness — reproducible builds. Without `--clean`, prebuild merges into existing native files and merge conflicts are silent and weird.

### When to prebuild

- After changing `app.json` (any field).
- After adding or removing a config plugin.
- After bumping `expo` SDK or `react-native-tvos`.
- After changing the banner or icon.

### When NOT to prebuild

- After changing only JS/TS code in `packages/shared-ui` or `apps/expo-multi-tv/src/`. JS bundles don't require regeneration.
- After updating a non-native dependency. Prebuild is for native config; JS deps don't need it.

Unnecessary prebuilds cost 60–120s and risk wiping any custom native edits (which the agent shouldn't have made, but).

## SDK version pin

The template ships with Expo SDK 51 and `react-native-tvos@0.74-stable` (or whatever the README states — verify on clone). Compatibility table:

| Expo SDK | react-native-tvos version | Notes |
|----------|---------------------------|-------|
| 51 | `0.74-stable` | Template default |
| 52 | `0.76-stable` | Newer; verify all deps |
| 54 | `0.81-stable` | Latest at time of writing; newest TV features |

If the user requests a newer SDK, bump deliberately:
1. Update `expo` and `react-native` (the alias to `react-native-tvos`) in **both apps**.
2. Update transitive deps that have SDK constraints (`expo-router`, `expo-font`, etc.).
3. `yarn install`.
4. `expo prebuild --clean`.
5. Build for each platform; expect to fix 1–3 small issues per major SDK bump.

The agent should not silently bump. SDK changes are visible diffs.

## EAS profile (when EAS Build is in use)

```json
// eas.json
{
  "build": {
    "preview-tv-android": {
      "extends": "preview",
      "env": { "EXPO_TV": "1" },
      "android": { "buildType": "apk" }
    },
    "preview-tv-ios": {
      "extends": "preview",
      "env": { "EXPO_TV": "1" },
      "ios": { "simulator": false }
    }
  }
}
```

From giolaq/tv-build-harness, MIT-0.

More from giolaq/tv-build-harness