Elaborate README Usage

[slaweet]

Question

I didn't find in the readme a clear statement about what the plugin does (Does it only generate a CSS file? Or it incorporates the generated styles?). I think it would fit in the "Usage" section of Readme.

From trying it out, the only thing I saw it does is that it generates index_critical.min.css. So I assume the plugin doesn't do the next step which is to inline it in my index.html and make the original index.css a non-render-blocking request.

So I think the "Usage" section of Readme should be extended with something like this:

After you've set up the plugin as above, run your build and it generates index_critical.min.css.

You should include index_critical.min.css in your index.html which can be done with the following code snippet: [ SNIPPET HERE (I have no clue how to do this) ]

You also need to make your original CSS files to be deferred which can be done with the following code snippet: [ SNIPPET HERE (I have no clue how to do this) ]

Additional context

I didn't use https://github.com/addyosmani/critical before so I don't know how it's expected to work, I only know its goal based on reading https://developer.chrome.com/docs/lighthouse/performance/render-blocking-resources/. I would expect that many people will be in a similar situation to me, which is why I spent my time writing this issue instead of trying to google for how to do it myself.

I'm trying to use this with Vite.

[khalwat]

The problem is, it would be very platform-specific in terms of how you'd actually accomplish that.

The code snippet would be different for every platform under the sun, so it's left as an exercise to the reader.

[slaweet]

@khalwat thank you for your reply.

I don't know what you mean by platforms here. I thought the platform is rollup. Is it other tools like Vitejs build on top of Rollup?

It's often the case that just a few of the most used platforms account for a vast proportion of users. So it might still be very useful to have some examples that serve those most used platforms' users and give at least some high-level hints for the rest.

So the readme could contain something like this;

After you've set up the plugin as above, run your build and it generates index_critical.min.css.

You should include index_critical.min.css in your index.html. The implementation is platform-specific, for example, in platform 1 it's done this way: [ SNIPPET IN PLATFORM 1 ] Or in platform 2 this way: [ SNIPPET IN PLATFORM 2 ]

You also need to make your original CSS files be deferred. The implementation is platform-specific, for example, in platform 1 it's done this way: [ SNIPPET IN PLATFORM 1 ] Or in platform 2 this way: [ SNIPPET IN PLATFORM 2 ]

[khalwat]

Rollup isn't always going to be the thing that injects the Critical CSS. If you're using it with a CMS, you'll use that CMS's native methods to inject the critical CSS.

Basically, there are 100's of different ways to render a template using a variety of platforms and tooling, and that's why presenting an example doesn't make a whole lot of sense.

If you want to give me an example for your use case, I'd be happy to label it and include it in the README.