Add support for critical CSS inlining with App Router

[mlstubblefield]

To Reproduce

1. Create a new next.js repository on vercel
2. Update next config
   const nextConfig = { experimental:{ optimizeCss: true } }
3. Add critters package - npm install critters
4. Host the page on vercel
5. Run the homepage of the app through webpage test https://www.webpagetest.org/result/231027_BiDcZF_FDJ/1/details/#waterfall_view_step1

Critical CSS is blocking :( and not optimized!

Current vs. Expected behavior

Before the appDir, critical css was inlined and FCP would be really really fast.
Now, you can see that FCP is behind the blocking CSS!

Just look at this waterfall https://www.webpagetest.org/result/231027_BiDcZF_FDJ/1/details/#waterfall_view_step1

[thaophamvan]

There is no way to inline critical CSS on App router. I can't find any solution to do it now. I don't know why Nextjs not support for App router

@mlstubblefield do you have any solution to solve it now?

[mlstubblefield]

Yea, it's a bummer- we saw huuuge improvements in our FCP when we first added critters, so I'm sad to see it no longer function.

[nilskaspersson-imtf]

Same. To be frank, I'm quite confused why the web dev community seemingly has abandoned efforts to inline the critical path. It is such a massive performance improvement.

[leerob]

Critters does not support streaming. This experimental flag works in the Pages Router (no streaming) but does not work with the App Router (has streaming). I've updated this issue to be a feature request and converted it to a discussion.

[thaophamvan]

Head tag of app router is not allowing to push inline CSS. So i have to put it on body tag

[rc-markzhou]

I am also looking into a way where I can put all css styles into a style tag which gets injected to head rather than requesting from external css files to improve the LCP etc.

What I have tried so far,

1. Use Cloudflare worker script to parse the HTML and find the external CSS request, make a fetch call for the external CSS file and replace the link tag with a style tag which holds the CSS content. It works, but obviously there is a mismatch with SSR and CSR output. However, I didn't notice any impact from end user perspective.
2. Config the webpack to use style-loader with insert: 'head' option. However, it doesn't work for SSR.

[fluidprompter-ben]

@rc-markzhou would you mind sharing your style-loader webpack config? I'm curious to try it with static site generation with NextJs app router.

FYI, considering your 1st option mentioned cloudflare, I export static nextjs site and host on cloudflare pages and use pages functions (essentially workers) to supplement my static site with server side code and do not use NextJS for middleware/redirects/etc. I found this is almost 200% faster than SSR with next-on-pages (though maybe next-on-pages edge runtime isn't as fast as vercel, I don't know). I currently average FCP/LCP around 650ms (desktop highspeed connection warm edge cache) with 100-200ms of that being CSS blocking loading.

[rc-markzhou]

@fluidprompter-ben Basically, this solution doesn't even generate the style tag on server side render. On client side, we gonna experience a Flash Of Unstyled Content(FOUC).

next.config.js

webpack: (config, options) => {
  if (!options.isServer && !options.dev) {
    config.module.rules.push(
      {
          test: /\.(sa|sc|c)ss$/,
          use: [
            {
              loader: 'style-loader',
              options: {
                insert: 'head',
                injectType: 'singletonStyleTag',
              },
            },
            {
              loader: 'css-loader',
            },
            'postcss-loader',
            'sass-loader',
          ],
        },
      )
    }

    return config
}

[Mifaresss]

I have different classNames in tag style and in html after npm run start. How you avoid this problem?

[mlstubblefield]

I would be very interested to hear performance comparisons from folks who were using optimizeCss in the Pages Router, versus streaming with the App Router, both in lab data and field data results.

Our results in the field were quite significant. Here are our field results using optimizeCss.

Something like 700-800ms improved FCP for mobile p90.
#29925 (comment)

[thaophamvan]

@leerob any update on this request?

[mlstubblefield]

I don't love the "not lots of upvotes" answer as it stops us from adopting appDir.
That being said, is there any direction that you could provide on how I could roll my own appDir + critters plugin?

[leerob]

Critters is incompatible with streaming, so there is not a workaround currently. Upvotes aren't the only way, but they're helpful!

[mlstubblefield]

Let's say critters was compatible, where would I/how would I plug it in? Would the StyledComponents implementation be similar in terms of how it "should work"?

[ghost]

@leerob Can you please give us some workaround for criticalCss which will be helpful for most developers

[tropikoder]

Google penalizes SEO when there's a slow LCP which happens every time when the critical path css isn't server-side rendered.

[markoleavy]

I'm testing a postbuild script to get inlined critical css with critters on html files for SSG pages, for the moment just in preview branches and on the homepage only.
I don't get any errors on the browser console, but lab performance didn't change significantly. Probably because of the large amount of inlined css, or some critter setting I'm not getting right. In particular I'm wondering which "preload" strategy would be better for next. I've tried default, swap, body and false, didn't notice any difference in test results.
I'm using version 13.4.12 with tailwind and next/fonts.
Here's the script:

import Critters from "critters";
import fs from "fs";

const critters = new Critters({
  path: ".next/static/css",
  publicPath: "/_next/static/css/",
  inlineFonts: true,
  preloadFonts: false, // next is already preloading them
});
async function editHome() {
  const inlined = await critters.process(
    fs.readFileSync(".next/server/app/index.html", "utf8")
  );
  fs.writeFileSync(".next/server/app/index.html", inlined);
}

new Promise(() => editHome());

[Mifaresss]

I think so too, but, as you can see, they are empty(

[markoleavy]

I'll let you know as soon as I implement next-intl, but if it's working
properly (and considering next app is full of unstable features and
unexpected behaviours, I'm afraid it's not) the html file must be
somewhere, otherwise it can't be served.

[vasujhawar]

I have implemented this
https://locize.com/blog/next-app-dir-i18n/
I got the html files generated after build, I will let you know if this script works or not.

[mlstubblefield]

As far as stragies go-- these were the default settings with the original "optimizeCss" flag...

next.js/packages/next/src/server/post-process.ts

Line 237 in 2f7721a

const Critters = require('critters')

{
ssrMode: true,
reduceInlineStyles: false,
path: renderOpts.distDir,
publicPath: `${renderOpts.assetPrefix}/_next/`,
preload: 'media',
fonts: false,
}

[mlstubblefield]

I tried to get this to work on pages w/ dynamic routes and had issues. In a lot of ways I'm having the same problem as @vasujhawar .

[calliope-codes]

tldr: Under Chrome "Slow 3G" conditions, it appears that inlining critical css makes the difference between good and mediocre/poor Core Web Vitals outcomes using the app router.

I have performed some lab benchmarks with a small GKE-deployed NextJS 14.1.0 ssr application with some suspended async operations (waterfall screenshot below). The waterfall suggests that inlining critical CSS would have a substantial positive performance impact on FCP in high-latency and/or low-bandwidth situations.

Below is a screenshot of the waterfall for the site, with disabled cache and Chrome "Slow 3G" (2 seconds request latency, 400 kbps down). Because Chrome adds two seconds of latency to each request, the fully-loaded HTML document is available two seconds before the critical (external) CSS finishes loading.

(In low-bandwith conditions, even with fetch priority set properly, the external CSS is competing with the loading Javascript, making it load even more slowly. If the CSS were inlined, the high latency and low bandwidth means the inline CSS/html has several seconds at 400 kbps down where it is the only resource being fetched, so high latency might actually help FCP in low-bandwidth situations!)

From a "qualitative" perspective, the slow FCP in this situation makes a lot of the (really cool) NextJS preloading UI optimizations less impressive, because the suspended SSR (especially with non-dynamic routes) finishes long before critical CSS is even ready! Without inlining critical CSS under these network conditions, preloading only looks good if the browser has a warm cache.

With my use case, I expect greater-than-normal visits under bad network conditions and no browser cache. The most important site content is text, and I want to display that immediately. (NextJS caching is a fantastic tool for this!) Aside from the inline CSS issue, the NextJS app router is performing beautifully. (In fact, CWV for mobile/desktop are generally well above 90%.) However, I feel bad that in spite of the technical backflips I'm doing, anyone inlining their critical CSS is going to massively outperform my app on FCP in bad network conditions.

I am also particularly sensitive to performance under bad conditions because I am hoping to use benchmarks as marketing materials (both personally as a developer and for the product), and it's tough to give a talk on web performance when your critical CSS is not inline. In some ways, I feel like the sword character from Indiana Jones, doing weeks of next-gen optimizations and being taken out by style={{backgroundColor: 'black'}}.

If I am misreading or misinterpreting that waterfall screenshot, please let me know. As always, thank you maintainers!

[welschmoor]

This is very important to get it working with the App Router!

[vasujhawar]

I am also waiting for further updates. How many upvotes are critical for critical css🤌🏻?@leerob @mlstubblefield

[markoleavy]

Are you working with static pages? Have you tried my script up here?
I'd be curious to understand why is not working as expected in my project.
Of course should work just for static pages and for FCP and LCP on site landing only.

[mlstubblefield]

I did try that approach, but any sort of dynamic routing does fall down @markoleavy.

[markoleavy]

This should apply to every static page for dynamic routes as well:

import Critters from 'critters';
import fs from 'fs';
import path from 'path';

const critters = new Critters({
  path: '.next/static/css',
  publicPath: '/_next/static/css/',
  inlineFonts: true,
  preloadFonts: false,
  preload: 'media',
});
function fromDir(startPath: string, filter: string) {
  if (!fs.existsSync(startPath)) {
    console.log('No .next folder found. Aborting.');
  } else {
    const files = fs.readdirSync(startPath);
    Promise.all(
      files.map(async file => {
        const filename = path.join(startPath, file);
        const stat = fs.lstatSync(filename);
        if (stat?.isDirectory()) {
          fromDir(filename, filter); //recurse
        } else if (filename.endsWith(filter)) {
          const inlined = await critters.process(
            fs.readFileSync(filename, 'utf8')
          );
          fs.writeFileSync(filename, inlined);
        }
      })
    );
  }
}

const promise = new Promise(() => fromDir('.next/server/app', '.html'));
promise.then(() => console.log('Postbuild done'));

[kenaku]

It's so frustrating, guys.
Spent like a month converting our middle size app to "app router" with all the bells and whistles, optimised what i could, fully adopted new patterns, dealt with dozens of issues with hydration errors and router quirks, integrated pretty awkward parallel routes and intercepted routes api's...
Only to land with like 10 seconds of a white screen on slow 3g.
Page router with css optimisation was 2 times faster to FCP and better LCP scores.

At this point im pretty much regret all this time spent. could live with "not ideal" ssr stuff in page router
Why even advertise this architectural changes as a path forward, if it's basically a downgrade on major metrics?

Sorry for the rant, but it was really painful and hard to pull off and now i guess i will have to revert refactoring because of this css stuff

[mlstubblefield]

I feel your pain.

[behitesh]

Hi. Is there an update about adding support for Critical CSS?

I Spent more than a week migrating my app to app-roter only to realize this feature was missing. It was a lapse on my part not to notice this before migration 😞

Considering how significant this can be for the page-load experience boost, I can't help but wait to have the support added to take my effort and app to production

If anyone is already working on this please do mention it here... I'd be happy to help in any way possible.

[markoleavy]

My implementation of Critters with post-build works on static htmls, but for some reason it doesn't improve performance on my project, and it does not work if you use page revalidation or ISR. Just static builds.
Could be a good starting point though.

[oliviertassinari]

Similar result from https://danielnagy.me/posts/Post_tsr8q6sx37pl. Inlining critical CSS matters on mobile according to this benchmark:

https://youtu.be/1gZmkpsVGkk?si=q8pNnWqkJLYzqjlt

Sebastian made a similar point:

reactwg/react-18#108

[lainosantos]

HI. Since there are problems dealing with critical css with dynamic routes, why aren't you just providing a possibility to use a global css embedded in the head? Many projects only use a global css with tailwind and this solution already solves many performance problems and user experience. This is frustrating, an entire application being limited to already known performance problems.

[javascripter]

You can use Tailwind CLI to generate css file sot my script will work for inlining Tailwind as well.
Layout files are server components and executed on the server only so you can load npm postcss package and manually process files yourself instead of Tailwind CLI as well.

In general, I don't recommend inlining Tailwind CSS files though. If you do that you cannot cache CSS files between requests and you end up sending all the utility classes used in the app on every page request.
If you still must do so, I recommend using Tailwind CLI as it's less complicated to setup.

[fluidprompter-ben]

If you do that you cannot cache CSS files between requests and you end up sending all the utility classes used in the app on every page request.

@javascripter this doesn't usually apply as most navigation in a nextjs site is a "soft navigation" and will not reload an inlined element in the header if done correctly. Vercel just needs to inject the inline CSS in the , NOT include CSS in the page partial resources for hydration or soft navigation and then everyone's page load performance will increase. The only trade-off here is if you had a lot of localized CSS styles (many 10's of KB) that made the initial payload so much larger that its better to code split styles for various pages - but for almost all normal sites you are better off with a slightly larger number of initial bytes in a single request than splitting those bytes over multiple sequential render blocking requests. IMHO, the whole of idea of "streaming" responses in nextjs is missing the mark for any static website such as a marketing website and is really focused on "apps" where there are a lot of different components and views with lazy loaded app data, etc. Vercel wants to replace CRA with a better thing and in doing so is leaving behind all the people who just wanted to build normal websites with React.

[zipme]

vercel-labs/next-partial-prerendering@b06d388
and it seems this is the current workaround..

[samcx]

@zipme That works as well, but what we will recommend (I still need to write this up as a follow-up below) does not use dangerouslySetInnerHTML. It uses Link Headers.

[rc-markzhou]

How do we keep only necessary styles from both tailwind and custom classnames (i.e. defined via tailwind.config)?

[samcx]

Hi everyone,

Just want to give an update that our team has recently discussed critters/this discussion further! As mentioned above, this is unfortunately currently not compatible with App Router because of streaming.

We're currently investigating how this would compare with Partial Prerendering (PPR) via a method like link-header prefetching, which could be an alternative way of achieving the same performance benefits as critters. We will report back on this thread with new updates!

[humet]

@markoleavy no we had those loading as well.

[markoleavy]

Loading both style tag and the css with high priority is certainly not the best option.
Editing the static html file with Critters as in my postbuild script, would put the css in a style tag in the head and at the same time moves the <link rel="stylesheet" tag at the end of the body to postpone it's load (behaves differently based on the preload prop). Unfortunately there are some issues I've found testing it:

• This <script> tag containing a RSC payload reintroduce the <link rel="stylesheet" tag in the document as soon as next begins the hydration process, making the css file loading concurrent with LCP images and other js files.

<script>
self.__next_f.push([1,"5:I[4687,[],""]nc:I[74242,[],""]nd:[]n0:[[
["$","link","0",
{
"rel":"stylesheet",
"href":"/_next/static/css/f1821db79a35143b.css",
"precedence":"next",
"crossOrigin":"$undefined"}]],
["$","$L5",null,{
"buildId":"4",
// etc..
<script/>

• Even if we were able to remove that part of the RSC payload, I'm not sure that moving the stylesheet tag to the end of the body would really postpone it's loading. Probably using the proppreload: 'swap' is the best option to obtain that result (see doc here), but can't be tested until the next payload is removed.

A possibility - rough and risky - could be editing the static html inside the postbuild script with a tool like cheerio and remove the link rel part from the RSC payload from the static html. @samcx do you think it might be a viable workaround?

[ke1vin4real]

@jakub300 @ke1vin4real can you try this as post build command?

Injecting the critical styles to head tag solved my problem

<style
  id="global-style"
  dangerouslySetInnerHTML={{
    __html: fs.readFileSync(path.join(process.cwd(), 'path', 'global.css'),'utf8')
  }}
/>

[markoleavy]

@ke1vin4real and how did you removed the css blocking request?

[mlstubblefield]

@ke1vin4real and how did you removed the css blocking request?

Agreed- while it's easy to inject the styles, we still need to eliminate the blocking requests.

[markoleavy]

Method for SSG static pages only

I've worked a few hours on my previous script and I got it working. No css is loaded on first-page landing (when the html file is effectively used), so no blocking request (actually no css request at all) nor additional css kbs.
When navigating to a new page, client side navigation opts in and css files are loaded.

In my case I had no significant improvement on performance tests, so I haven't fully tested it, as I'm probably not gonna use it in production. Anyway I got a perfect layout on all the pages I tested, within a quite complex tailwind based app.

Hope it might be helpful for someone!

Implementation

• Install tsx, critters and cheerio as dev deps.
• Add this script command to your package.json

"postbuild": "tsx src/postbuild.ts",

• Create a new file named postbuild.ts inside src folder (or wherever you want) containing this script.

/* eslint-disable no-useless-escape */
import { load } from 'cheerio';
import Critters from 'critters';
import fs from 'fs';
import path from 'path';

const critters = new Critters({
  path: '.next/static/css',
  publicPath: '/_next/static/css/',
  inlineFonts: true,
  preloadFonts: false,
  preload: 'body',
  logLevel: 'error',
});
function fromDir(startPath: string, filter: string) {
  if (!fs.existsSync(startPath)) {
    console.log('No .next folder found. Aborting.');
  } else {
    const files = fs.readdirSync(startPath);
    
    // iterates over files and folders
    Promise.all( 
      files.map(async file => {
        const filename = path.join(startPath, file);
        const stat = fs.lstatSync(filename);
        
        // recursion in case stat is directory
        if (stat?.isDirectory()) {
          fromDir(filename, filter);
          
        // checks if the file is an html
        } else if (filename.endsWith(filter)) { 
        
          // inlines css and moves <link rel=stylesheet>s to body
          const inlined = await critters.process(
            fs.readFileSync(filename, 'utf8')
          );
          
          //writes critters' changes
          fs.writeFileSync(filename, inlined);
          
          //loads page on cheerio (html editor)
          const page = load(fs.readFileSync(filename, 'utf8'));
          page('script')?.each((i, elem) => {
            const text = page(elem).text();
            
           //  If a <script> tag (RSC payload) contains a css import, removes it
            if (text?.match(/\[[^\]^\[]+_next\/static\/css\/.*?\.css.*?\]/)) {
              const newText = text.replaceAll(
                /\[[^\]^\[]+_next\/static\/css\/.*?\.css.*?\]/g,
                '[]'
              );

              page(elem).text(newText);
            }
          });
          
          //removes <link rel=stylesheet>s to avoid css loading. 
          // Remove this part in case you might need non-blocking css load
          page('[rel="stylesheet"]')?.each((i, elem) => { 
            page(elem).remove();
          });
          
          // writes cheerio's changes
          fs.writeFileSync(filename, page.html()); 
        }
      })
    );
  }
}
const promise = new Promise(() => fromDir('.next/server/app', '.html'));
promise.then(() => console.log('Postbuild done'));

• Build your website

[Danogot516]

I tried your script, but it did not seem to work correctly for me - it DID add the css into a style tag in the head of the SSG pages, but for some reason Critters just omitted some styles and selectors even though they were present in the markup and this would cause the pages to be loaded semi-broken.

I've been trying for weeks to increase our page speed score, removing libraries and shaving KBs from the bundle little by little, to absolutely no avail. I was able to make the first load JS 113kB and did all of the image optimizations possible and I still get a measly 45 score on mobile. The fact that I cannot use critical CSS inlining and webworkers for offloading the main thread of all the third-party scripts the marketing dept wants to load is really frustrating as I though the App router already had everything I would need to make a fast static website.

Sorry for the rant...

[markoleavy]

Hi @Danogot516, I'm sorry to hear it didn't work for you. I would be interesting to investigate why critters did fail to load part of the css, and see if there are possibile workarounds.
Apart from that, did you try to test the score of the broken page? Was it improved?

[Danogot516]

@markoleavy I did not test the speed. Dev tools lighthouse always seems to show drastically better results (~30 points) when compared to the pagespeed insights. I am not sure how to debug critters in this case, what I noticed is that I did not see any of the console logs in your scripts when running the build and postbuild scripts. I did git the css inlined, but for some reason critters just omitted parts of the styles - I would have two css rules .b {some rules}.b img{some other rules} and what I would get in the inlined css would only be .b img{rules}.

[gujral1997]

@samcx Do we have any ETA on this? This issue is having a lot of impact on our LCP and impacting our SEO performance.

[gujral1997]

@samcx I was hoping the vercel team would add it in the v15, but I don't see it in the changelogs :(

[jfbrennan]

Terribly disappointed. Not a fan of React, even less of a fan of React-based server frameworks, only confirms negative perceptions about this part of frontend-land.

It's an important feature for a server framework - please add support!

[samcx]

@gujral1997 v15 has necessarily landed yet—it's still a release candidate. It's going to land with React v19 when that's released on latest.

It's an important feature for a server framework - please add support!
@jfbrennan I don't disagree that we should add this!

There is work being done for this (although not directly mentioned in the PR) → #67715.

We will continue to share any important updates as they come!

[samcx]

@zipme

We are not knowingly pushing bugs to canary (almost every fix, new PR, needs to be accompanied by an updated/new test, and pass the rest of our ~6500+ tests), but the idea behind a canary is that the code is bleeding edge and not thoroughly battle tested. It's used to immediately push up fixes, but that can obviously have its drawbacks if we happen to cause and miss a regression. Another thing to note is that we do ship breaking changes in canary without documentation. If you have testing in place, I would say it's definitely viable to be using canary in Production (there are folks who definitely do so).

With platforms like Vercel, if you find a regression, you should be able to instantly revert your Production to the previous Production Deployment on a previous canary.

[Mr-Pepe]

Next.js (React to be more specific) will automatically calculate what are the best assets that should be included in the Link Headers.

@samcx Does it do that automatically in any case with Next.js 15 / React 19 or only when setting optimizeCss?

[samcx]

@Mr-Pepe It should already be happening now if necessary. We just expanded the max headers size, so it should be happening more frequently. It's confusing as to when this actually happens, so currently I intend to show this in action (e.g., artificially delay a page) in an explanation.

[markomitranic]

@zipme I think this is possible to backport to another minor 14 release. Are you not able to use the latest canary version?

@samcx thanks for the explanations and all the work so far, I am very much looking forward to using this. Personally I think its silly, especially when using Tailwind, but metrics are metrics, and we are frequently asked to fix this issue for our clients, so it is a major help knowing that the Next team is aware and has a plan.

Should we expect a v14 release of this?

It is not possible to move to v15 or canary with production projects, and this issue is quite time sensitive due to decreasing lighthouse scores that heavily affect SEO. I wish v15 was closer, but as things stand it is on rc~120++ and without a clear end date in sight (at least for those of us looking from the outside).

The SEO stakeholders keep asking me to solve this, and I keep having no answer for them, so it'd be super useful for me to know if we will be waiting for v15 or should expect this in v14 in the next few weeks. :)

[samcx]

@markomitranic Unfortunately, there will not be a v14 release for Link Headers (I misspoke earlier, my apologies).

A few months ago I spoke how better performance (comparable to critically inlining CSS) could be achieved via PPR → Link Headers. What I didn't mention clearly is that this is only achievable by PPR because we can quickly send a static shell, which then makes it feasible to send Link Headers with that static shell. You can also use PPR with v14 canary (I believe this requires React 19), which at that point, it's just better to be on v15 canary.

In the meantime, you will have to resort to other options such as → #59989 (reply in thread). I also see that in our example, we applied a similar option (for Tailwind) → https://github.com/vercel-labs/next-partial-prerendering/pull/22/files#diff-eca96d2c09f31517696a26e1d0be4070e1fbab02831481bed006e275741d030b.

The next v15 release is coming very soon! There is a draft PR if you look around (don't want to spoil it yet!). There is another un-related CSS conversation that is happening that can be beneficial for FCP performance.