Feature request: Add @match directive support

[bezustally]

Overview

I would like to add support for the @match directive in usercss files, similar to other CSS preprocessors.

Use Case

Currently users can only use @url, @urlprefix, @domain, and @regexp directives for targeting. The @match directive would provide a more flexible way to specify URL patterns.

Proposed Implementation

• Add @match directive parser in meta-parser.js
• Update style matcher to handle @match patterns
• Enhance usercss compiler for @match compatibility
• Update UI to display @match patterns with favicons

Example Usage

@match https://example.com/*
@match https://*.github.com/*

body {
  background: red;
}

Benefits

• Better style targeting precision
• Enhanced compatibility with other CSS preprocessors
• Improved user experience with visual domain indicators

Would this feature be welcome in the project?

[tophf]

Thanks for the idea, but I don't agree with the benefits you listed:

Better style targeting precision

1. We already have max precision via regexp
2. This idea seems to treat the entire style as one section, but our current implementation allows multiple sections with different targets within one site or any number of [related] sites.

Enhanced compatibility with other CSS preprocessors

Which ones and how specifically?

Improved user experience with visual domain indicators

We already show domain indicators in the Style manager page, we can do it in other places as well. It doesn't require a new syntax.

[bezustally]

Thanks for the feedback! You're absolutely right about existing functionality.

Main reason - Compatibility

The main reason is compatibility - many users come from Tampermonkey/Greasemonkey/Userscripts (Safari) where @match is the standard way to target URLs. When they switch to Stylus, they expect the same syntax to work.

Use case

Users migrating from other tools expect this to work:

@name Test Style
@match https://*.github.com/*
@match https://*.google.com/*

body {
  background: red;
}

This style would only apply to GitHub and Google pages, not to other sites.

Why @match specifically?

• Familiar syntax: Tampermonkey/Greasemonkey/Userscripts users are used to @match syntax
• Simplicity: @match https://*.github.com/* is simpler than @regexp ^https://[^/]*\.github\.com/
• Standard: @match is the standard way to target URLs in other tools

Implementation

@match works as a regular section directive (like @domain, @url, @regexp) - each section is checked independently.

Compatibility

Users migrating from Tampermonkey/Greasemonkey/Userscripts expect @match to work in Stylus. This reduces friction when switching between tools.

The implementation would be straightforward - just another directive type alongside the existing ones.

Would this make sense as a compatibility enhancement for users coming from other tools?

[tophf]

Since UserCSS section syntax is pure CSS by design to allow for multiple sections, I don't think having a one-section variant is necessary. This topic was discussed multiple times in the past and I had the same doubts. I would rather we add an import/convert button to our UI which transforms simple patterns:

• https://*.github.com/* to @-moz-document domain("github.com")
• https://site/prefix* to @-moz-document url-prefix("https://site/prefix")
• https://site/path to @-moz-document url("https://site/path")

@eight04, WDYT?

[tophf]

Users migrating from other tools expect this to work:

This is not a valid UserCSS syntax. Please see examples in https://github.com/openstyles/stylus/wiki/Writing-UserCSS

[tophf]

@match works as a regular section directive (like @domain, @url, @regexp) - each section is checked independently.

No, in the CSS @match resides in the metadata comment for the entire style, whereas domain, url, url-prefix, regexp are functions in CSS, not directives, and they don't have @.

[eight04]

There were some discussions about moving to @match. The general conclusion was: The benefits are unclear, but the drawbacks are obvious.

Pro:

1. The syntax would stay with userjs & browser.userScripts API.
2. Wildcard * is easier to read/write compared to regex.

Con:

1. It only works with single section.
2. It won't work with preprocessors anymore because it is no longer in the code but in the comment.
3. Because of 1 & 2, only part of usercss can benefit from the new syntax.
4. Any tool processing usercss (not only this extension but also websites, other dev tools, etc) has to maintain two different matching system, increasing complexity.
5. Overall, this change would likely raise the complexity instead of reducing it.

See also: https://github.com/openstyles/stylus/issues/343 https://github.com/openstyles/stylus/issues/1794 https://github.com/greasyfork-org/greasyfork/issues/656

Users migrating from Tampermonkey/Greasemonkey/Userscripts expect @match to work in Stylus. This reduces friction when switching between tools.

For authors, using CSS functions shouldn't be a problem.

For users, Stylus already has a wildcard matching system:

---

I'm not completely against the idea though. We may also want to switch at some point e.g. when the browser supports a super fast/lightweight native userscript API that benefits users a lot.

Since MV3 also has userScripts API, maybe we can implement a subsystem that manages part of usercss which is compatible with matches.

If that works well, we may want to add match to usercss. Then we can discuss whether to use directive, CSS function, or both.