# Deep link URL patterns are correctly mapped to screens

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

## Why it matters

A deep-link config that points to a screen name that does not exist, or a pattern parameter (`:id`) that the screen reads under a different key (`route.params.productId`), causes React Navigation to resolve the link to nothing, pass `undefined` to the screen, or render with a silently missing id. The user taps a product link and lands on a blank detail page; telemetry shows a navigation success but the screen queries `undefined` and renders an error state.

## Severity rationale

Critical because pattern mismatches turn every deep link into a silent failure that never throws.

## Remediation

Align every pattern parameter with the exact key the screen reads from `route.params`. If the pattern is `product/:id`, the screen must read `route.params.id`:

```tsx
const linking = {
  config: { screens: { ProductDetail: 'product/:id' } },
}

function ProductDetailScreen() {
  const { id } = useRoute().params as { id: string }
  // fetch product by id
}
```

Grep the codebase for each screen name to confirm exact casing and parameter keys match.

## Detection

- **ID:** `pattern-mapping`
- **Severity:** `critical`
- **What to look for:** Examine the `linking.config.screens` object. Each URL pattern must map correctly to a screen's route name. Check for typos in screen names, incorrect parameter names (e.g., `product/:id` should match a screen using `route.params.id`), and pattern syntax issues.
- **Pass criteria:** Count all URL pattern-to-screen mappings. Every URL pattern in the config maps to a valid screen name that exists in your navigator with no more than 0 mismatches. Parameter names in patterns (e.g., `:id`) must match the parameter names used in screens (e.g., `route.params.id`).
- **Fail criteria:** Screen names in config do not match actual navigator screen names. Parameter names are inconsistent (pattern says `:id` but screen accesses `route.params.productId`). Do NOT pass when screen names match case-insensitively but differ in exact casing.
- **Skip (N/A) when:** Never — deep link patterns must map correctly.
- **Detail on fail:** Identify mapping mismatches. Example: `"Config maps 'user/:id' to screen 'UserProfile' but actual screen name is 'Profile'"` or `"Pattern uses ':productId' but screen accesses 'route.params.id'"`
- **Remediation:** Ensure exact consistency between pattern names and screen implementations. For a product detail screen:

  ```tsx
  // linking config
  const linking = {
    config: {
      screens: {
        ProductDetail: 'product/:id'  // pattern parameter is :id
      }
    }
  }

  // ProductDetailScreen
  function ProductDetailScreen() {
    const route = useRoute()
    const productId = route.params.id  // must match pattern parameter name
    // ... render
  }
  ```

Taxons: reference-integrity, user-experience

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