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.

linkapp.config.ts

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

Define match rules

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.

url_match_rules: {
  hostnames: ["example.com"],
  patterns: [{ pathname: "/products/*" }],
  notPatterns: [{ pathname: "/products/admin" }]
}

Pattern syntax cheatsheet

Patterns use 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:

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:

package.json

{
  "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.