Improve matchUtilities
API and make it work with the AOT engine
#4232
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Written by @adamwathan
This PR improves the
matchUtilities
plugin API used by the JIT engine to make it both simpler and more declarative, and also make it compatible with the AOT engine. These improvements are still considered to be in preview, and may change without adhering to semantic versioning until the JIT engine is totally stable.The main goal of this is to make it so users don't have to conditionally use different APIs depending on the mode. For example, this is what you might have had to write prior to these improvements:
With these improvements, you can just use
matchUtilities
and it'll still work in AOT mode. To make this possible, we needed to rework the actual API ofmatchUtilities
, but the changes are actually a huge improvement for both engines and make the code a lot more declarative and terse. Here's what the API looks like now:You no longer have to specify the actual class name which is really nice — that is automatic now since you aren't really allowed to change it anyways, you have to return a rule that matches the detected class name in the HTML or of course nothing is going to work, so before this change all that really was was an opportunity for someone to make a mistake.
So now you just need to return the declarations, which is all you need for 99% of cases. You also pass in the
values
(which is used by AOT mode to generate all the right classes, and by JIT mode to know which classes are valid matches for the lookup and which should be discarded), andvariants
(only used by AOT mode). Thetype
option is used to coerce arbitrary values (likebackdrop-contrast-[0.5]
) and sort of specify what sort of input is valid.Valid options are
any
,color
,length
,lookup
,angle
, andlist
. Might refine these as we discover more possible types, especially thinkinglist
needs a bit of thought.The only issue with this API is if you ever do need to generate more than just a basic utility class. There are two main situations that need to be dealt with:
::placeholder
. Conveniently Tailwind supports nesting in plugins, so you just handle this with the&
operator:includeRules
helper that lets you add arbitrary raw CSS rules whenever a match is detected. Looks like this:Overall really happy with this API, drastically simplifies a lot of stuff without sacrificing any power. We had to make some changes to the actual generated CSS order in Tailwind but nothing that affects the actual behavior, so should be fine to include this in 2.2 once we find a couple other quick features to include.