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

# URL Matching

> Auto-suggest your LinkApp when users enter matching URLs

URL match rules surface your LinkApp when creators paste URLs that look like the ones you specify. They improve discovery only—creators can still add your app manually for any other URL.

```ts linkapp.config.ts theme={"system"}
export default {
  url_match_rules: {
    hostnames: ["youtube.com", "youtu.be"],
    patterns: [
      { pathname: "/watch", search: "v=:videoId" },
      { pathname: "/:videoId" }
    ]
  }
}
```

## Define match rules

```ts theme={"system"}
url_match_rules: {
  hostnames: string[],
  patterns?: Pattern[],
  notPatterns?: Pattern[]
}
```

* `hostnames` (required) — domains your app supports. List every variant you expect (`youtube.com`, `www.youtube.com`, `m.youtube.com`, etc.).
* `patterns` — optional pathname/search combos that must match. Leave empty to match any path on the hostnames.
* `notPatterns` — optional exclusions, useful when matching a broad path with specific carve-outs.

```ts theme={"system"}
url_match_rules: {
  hostnames: ["example.com"],
  patterns: [{ pathname: "/products/*" }],
  notPatterns: [{ pathname: "/products/admin" }]
}
```

## Pattern syntax cheatsheet

Patterns use [URLPattern](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) semantics.

| Pattern                                             | Matches                            | Tip                              |
| --------------------------------------------------- | ---------------------------------- | -------------------------------- |
| `{ pathname: "/watch" }`                            | `https://youtube.com/watch`        | Exact path                       |
| `{ pathname: "/:id" }`                              | `https://youtu.be/abc123`          | Named segment                    |
| `{ pathname: "/products/*" }`                       | `https://example.com/products/a/b` | Wildcard suffix                  |
| `{ search: "v=:videoId" }`                          | `?v=dQw4w9WgXcQ`                   | Include both key and placeholder |
| `{ hostname: "m.youtube.com", pathname: "/watch" }` | `https://m.youtube.com/watch`      | Override host per pattern        |

Paths are case-sensitive. Query parameters can appear in any order.

## Test your rules

Use the CLI to confirm matches before shipping:

```bash theme={"system"}
linkapp test-url-match-rules "https://youtube.com/watch?v=dQw4w9WgXcQ"
```

Positive matches print the LinkApp slug; failures show the part that missed. Add a script for quick re-testing:

```json package.json theme={"system"}
{
  "scripts": {
    "test:url": "linkapp test-url-match-rules"
  }
}
```

## Troubleshoot fast

* Double-check hostnames—include `www`/mobile/regional variants explicitly.
* Ensure named parameters keep the colon (`/user/:id`, not `/user/id`).
* Declare query parameters with both the key and placeholder (`search: "v=:videoId"`).
* Replace overly broad wildcards if you see unexpected matches.

## Best practices

* Start specific, then add broader fallbacks (`/watch` before `/:id`).
* Document uncommon paths with inline comments for future maintainers.
* Keep the total number of patterns below the 50-pattern limit.
* Re-run `linkapp test-url-match-rules` after every config change.