# Deep links are defined for all primary linkable screens

- **Pattern:** `ab-001856` (`mobile-navigation-linking.deep-linking.deep-links-defined`)
- **Severity:** critical
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-001856
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-001856)

## Why it matters

Without a `linking` config, every marketing email, push notification, universal link, and share-sheet URL dumps the user on Home with no context — breaking attribution, re-engagement, and the entire growth loop. This violates the App Store Readiness expectation that `app.json` scheme declarations route to real screens, and it silently kills conversion from paid acquisition channels because the destination screen the ad promised never loads.

## Severity rationale

Critical because every external acquisition channel and notification loses its destination when deep links are not defined.

## Remediation

Define a `linking` object that maps every linkable screen to a URL pattern and pass it to `NavigationContainer`. Put this next to the root navigator in `src/navigation/linking.ts`:

```tsx
export const linking = {
  prefixes: ['myapp://', 'https://myapp.com'],
  config: {
    screens: {
      Home: '',
      ProductDetail: 'product/:id',
      Profile: 'profile/:userId',
    },
  },
}
```

Mirror every `prefix` in `app.json` under `scheme` and in your iOS `Associated Domains` entitlement.

## Detection

- **ID:** `deep-links-defined`
- **Severity:** `critical`
- **What to look for:** Examine the `linking` config object passed to `NavigationContainer`. It should have a `prefixes` array (e.g., `['myapp://', 'https://myapp.com']`) and a `config` object mapping URL patterns to screen routes. Check that all screens users should be able to access via links (Home, Product Detail, User Profile, etc.) have URL patterns defined.
- **Pass criteria:** Enumerate all URL patterns in the linking config. Deep link `config` object maps URL patterns to all primary screens with at least 3 screen routes defined. Prefixes include at least 1 custom scheme (e.g., `myapp://`) and at least 1 web domain (e.g., `https://myapp.com`) if applicable. Before evaluating, extract and quote the `prefixes` array from the linking config.
- **Fail criteria:** No `linking` config provided to `NavigationContainer`. Only a subset of linkable screens have URL patterns. Prefixes are missing or incomplete. Do NOT pass when a linking config exists but has 0 screen mappings.
- **Skip (N/A) when:** The app is not meant to receive deep links (strictly internal navigation, no intent-based linking).
- **Cross-reference:** The App Store Readiness audit (`mobile-store-readiness`) checks app.json scheme configuration that must align with deep link prefixes.
- **Detail on fail:** List missing deep link patterns. Example: `"Product detail pages not mapped in linking config. No pattern for '/product/:id'"`
- **Remediation:** Define a `linking` config with patterns for all linkable screens. In your navigation setup file:

  ```tsx
  const linking = {
    prefixes: ['myapp://', 'https://myapp.com'],
    config: {
      screens: {
        Home: '',
        ProductDetail: 'product/:id',
        Profile: 'profile/:userId',
        Settings: 'settings'
      }
    }
  }
  ```

  Every screen that users might access via a link must have a URL pattern defined. Pass this config to `NavigationContainer`:

  ```tsx
  <NavigationContainer linking={linking}>
    {/* navigators */}
  </NavigationContainer>
  ```

Taxons: user-experience, reference-integrity

HTML version: https://auditbuffet.com/patterns/ab-001856