Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 36 ยท Manifest V3 and Structure

Match Patterns: Choosing Where to Run

Master match patterns for content_scripts and host_permissions: scheme, host, path, wildcards, all_urls, exclude_matches and common mistakes, with a live matcher.

Almost every extension has to say which web pages it applies to. You do that with match patterns: short URL templates used in content_scripts.matches, host_permissions, web_accessible_resources and externally_connectable. They look like URLs with wildcards, but they follow stricter rules than regular expressions or globs.

The shape of a pattern

TEXT
<scheme>://<host>/<path>

Every pattern has all three parts.

JSON
"matches": ["https://www.example.com/articles/*"]
  • scheme: http, https, * (http or https), file, ftp, ws, wss or urn.
  • host: a domain name, * (any host), or *.example.com (the domain and all its subdomains). A wildcard is only allowed as the whole host or as a leading *..
  • path: starts with / and may contain *, which matches any characters, including none. The path must be present: https://example.com is invalid; write https://example.com/*.

Examples

Pattern Matches
https://example.com/* Any page on example.com over HTTPS (not subdomains)
https://*.example.com/* example.com and every subdomain
*://example.com/* http and https on example.com
https://example.com/blog/* Only paths under /blog/
https://*/* Any HTTPS site
<all_urls> Any http, https, file or ftp URL
file:///* Local files (the user must also allow file access)

Things people expect but do not work:

  • https://*example.com/* โ€” the * must be followed by a dot.
  • https://example.com/*.html โ€” fine; * in the path matches anything: this matches paths that end in .html.
  • https://example.*/* โ€” a trailing host wildcard is not allowed.
  • Query strings and fragments: the path part is matched against the path and query, but never the #fragment. Many developers add ?* accidentally; just use /*.
  • Port numbers: https://example.com:8080/* does not match as expected; ports are ignored unless you use localhost style, which matches any port.
flowchart LR
    U["https://blog.example.com/posts/1?x=2"] --> S{"scheme matches?"}
    S -->|yes| H{"host matches?"}
    H -->|yes| P{"path matches?"}
    P -->|yes| OK["Pattern matches"]
    S -->|no| NO["No match"]
    H -->|no| NO
    P -->|no| NO

All three parts must match.

Include and exclude

content_scripts accepts extra filters:

JSON
"content_scripts": [{
  "matches": ["https://*.example.com/*"],
  "exclude_matches": ["https://admin.example.com/*"],
  "include_globs": ["*article*"],
  "exclude_globs": ["*print*"],
  "js": ["content.js"]
}]

exclude_matches removes pages that would otherwise match. The *_globs keys add loose substring-style filtering on the full URL: * means any characters and ? means one character. Use match patterns first; reach for globs only for what patterns cannot say.

A live matcher

You do not have the real Chrome matcher here, but its rules are small enough to model. Try your own patterns and URLs in the code.

JS Match pattern tester (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Safer patterns, narrower permissions

The wider your patterns, the more warnings users see at install: <all_urls> becomes "Read and change all your data on all websites". Reviewers also ask why you need that. Good habits:

  1. Name the exact sites when you know them.
  2. Use optional_host_permissions and request access when the user asks for a feature (see the permissions chapter).
  3. Use activeTab for "act on the page I am looking at, when I click" features, which needs no host permission.
  4. Test your negative cases: URLs that must not match.
JS Which pattern is the narrowest?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which pattern matches example.com and all its subdomains over HTTPS?

    A host wildcard must be a leading "*." as in *.example.com, which also matches the bare domain.
  2. 2. Why is the pattern https://example.com invalid?

    Every match pattern needs scheme, host and path. Write https://example.com/*.
  3. 3. What does exclude_matches do in a content script entry?

    It subtracts URLs from the set selected by matches.
  4. 4. Which pattern gives users the scariest install warning?

    <all_urls> asks to read and change data on every site, which is why narrow patterns or optional permissions are preferable.

Summary

  • A match pattern is scheme://host/path, with all three parts present.
  • *. at the start of the host matches subdomains; * in the path matches anything.
  • exclude_matches and the glob keys refine content_scripts.
  • Prefer narrow patterns, activeTab and optional host permissions.
  • Test both URLs that should and should not match.

Next: Building a Popup