useCssCascadeLayers not adding @layer blocks

[jaredmcateer]

Reading the plugin docs for Css Cascade Layers enabling future.v4.useCssCascadeLayers when using @docusaurus/preset-classic should be all I need but while it does something it's not adding @layer blocks

• I enabled future.v4.useCssCascadeLayers
• I later tried enabling future.expiremental_faster
  • And added prereqs @docusaurus/faster and future.v4.removeLegacyPostBuildHeadAttribute
  • However output was the same
• Running docusaurus start and docusuaurs build && docusaurus serve has same results

Output:

• There are no @layer blocks in styles.css
• Rules have :not(#\#):not(#\#) appended to them e.g:

Note:

• the first 302 lines are comments mostly just repetitions of the facebook copyright notice)

• In Chrome DevTools these are the listed layers (tcl is my layer):

• I did a regex search in devtools for @layer (?!tcl) and there were no matches (I also verified negative lookahead regex works in CDT search)

Config:

/** @type {import('@docusaurus/types').DocusaurusConfig} */
module.exports = {
  title: 'Component Library',
  tagline: 'A home for your component needs',
  url: 'https://example.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  favicon: 'img/favicon.svg',
  markdown: {
    hooks: {
      onBrokenMarkdownLinks: 'warn',
    },
  },
  organizationName: 'my-org',
  projectName: 'component-library',
  future: {
    experimental_faster: true, // Originally not set
    v4: {
      useCssCascadeLayers: true,
      removeLegacyPostBuildHeadAttribute: true, // Originally not set
    },
  },  
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          // Please change this to your repo.
          editUrl: 'https://github.com/my-org/component-library',
          remarkPlugins: [[require('@docusaurus/remark-plugin-npm2yarn'), { sync: true }]],
          sidebarCollapsible: false,
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ],
  plugins: [
    '@docusaurus/theme-live-codeblock',
    'docusaurus-plugin-sass',
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'docs-mobile',
        path: 'docs-mobile',
        routeBasePath: 'docs-mobile',
        sidebarPath: require.resolve('./sidebars-mobile.js'),
      },
    ],
    function aliasPlugin() {
      return {
        name: 'react-native-web-alias',
        configureWebpack() {
          return {
            resolve: {
              alias: {
                'react-native': 'react-native-web',
                'react-native-svg': 'react-native-svg-web',
              },
            },
          };
        },
      };
    },
  ],
  themeConfig: {
    liveCodeBlock: {
      playgroundPosition: 'bottom',
    },
    navbar: {
      title: 'Component Library',
      logo: {
        alt: 'Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          href: '/docs/intro',
          position: 'left',
          label: 'Web',
        },
        {
          href: '/docs-mobile/intro',
          position: 'left',
          label: 'Mobile',
        },
        {
          href: '/about',
          label: 'About',
          position: 'left',
        },
        {
          href: 'https://github.com/my-org/component-library',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
    footer: {
      links: [
        {
          title: 'Community',
          items: [
            {
              label: 'Documentation',
              href: 'https://example.com/docs',
            },
          ],
        },
        {
          title: 'More',
          items: [
            {
              label: 'GitHub',
              href: 'https://github.com/my-org/component-library',
            },
          ],
        },
      ],
      copyright: `Made with &#128150 by the UI Team.`,
    },
  },
};

Additional troubleshooting

• I ran npx docusaurus clear
• Verified docusaurus package should be up to date enough to support the feature

❯ yarn list --depth=1 | rg "@docusaurus/.*"
├─ @docusaurus/babel@3.9.2
├─ @docusaurus/bundler@3.9.2
├─ @docusaurus/core@3.9.2
├─ @docusaurus/cssnano-preset@3.9.2
├─ @docusaurus/faster@3.9.2
├─ @docusaurus/logger@3.9.2
├─ @docusaurus/mdx-loader@3.9.2
├─ @docusaurus/module-type-aliases@3.9.2
├─ @docusaurus/plugin-content-blog@3.9.2
├─ @docusaurus/plugin-content-docs@3.9.2
├─ @docusaurus/plugin-content-pages@3.9.2
├─ @docusaurus/plugin-css-cascade-layers@3.9.2
├─ @docusaurus/plugin-debug@3.9.2
├─ @docusaurus/plugin-google-analytics@3.9.2
├─ @docusaurus/plugin-google-gtag@3.9.2
├─ @docusaurus/plugin-google-tag-manager@3.9.2
├─ @docusaurus/plugin-sitemap@3.9.2
├─ @docusaurus/plugin-svgr@3.9.2
├─ @docusaurus/preset-classic@3.9.2
├─ @docusaurus/remark-plugin-npm2yarn@3.9.2
├─ @docusaurus/theme-classic@3.9.2
├─ @docusaurus/theme-common@3.9.2
├─ @docusaurus/theme-live-codeblock@3.9.2
├─ @docusaurus/theme-search-algolia@3.9.2
├─ @docusaurus/theme-translations@3.9.2
├─ @docusaurus/types@3.9.2
├─ @docusaurus/utils-common@3.9.2
├─ @docusaurus/utils-validation@3.9.2
├─ @docusaurus/utils@3.9.2

• I saw in another issue, Docusaurus faster option useCssCascadeLayers: true causes build errors #11220, that postcss and style-loader could be the cause of build issues even though I wasn't getting build errors I double checked but my versions were newer than known working.

❯ yarn why postcss
yarn why v1.18.0
=> Found "postcss@8.5.6"

❯ yarn why css-loader
=> Found "css-loader@6.11.0"

[slorber]

Can you please create a minimal runnable repro we could inspect using docusaurus.new ?

Our init template has CSS cascade layers: https://tutorial.docusaurus.io/

If you don't, there must be something on your site that breaks it.
Have you tried without Sass or React Native Web, for example?

[jaredmcateer]

I spent some time removing everything I could from my code and the starter template until I found the culprit.

My package.json was missing this:

  "browserslist": {
    "production": [
      ">0.5%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 3 chrome version",
      "last 3 firefox version",
      "last 5 safari version"
    ]
  }

It looks like it was deleted by someone cleaning up our dependencies 😅. It makes sense we need to target recent browsers supporting Cascade Layers but I would expected a warning or something.

[slorber]

This is how postcss-preset-env works: it downgrades your CSS syntax to what you configure.

There is no warning because why should there be if you purposefully target browsers that do not support CSS cascade layers (this is a reasonable thing to do, and a warning would be annoying)

[jaredmcateer]

There is no warning because why should there be if you purposefully target browsers that do not support CSS cascade layers (this is a reasonable thing to do, and a warning would be annoying)

I respectfully disagree, a lack of a non-official field in the package.json is, at best, an implicit request for broad support. That's assuming that the person removing it, intentionally omits it, and knows what it means to omit it. Enabling future.v4.useCssCadcadeLayers, OTOH, is an explicit request for modern browser features.

postcss-preset-env is an internal dependency, it isn't something that one implementing docusaurus explicitly includes in their project. I did my due diligence and looked at the configuration docs/api for anything I might be missing. Unless one knows to look at the Browser Support page you don't even get a hint of the internals needing a browerslist field and even then it only talks about breaking old browsers' JS by being too restrictive by default, nothing about CSS and nothing about it being overly permissive if missing.

Obviously there is the argument that one should not be casually removing things without knowing why it might be there. However people, especially inexperienced people, make mistakes and stuff like this can slip through the cracks in reviews when some team members aren't particularly diligent on PRs and/or are pressed for time and nothing is broken because of it (until later down the line). And trust me, removing stuff from configuration without showing your work is coming up in the retro.

[slorber]

I understand the idea, but not sure what we can reasonably do about it.

Should we emit a warning if there's no browserslist?

It's not reasonable for us to emit a warning if any CSS/JS downgrading happens. future.v4.useCssCadcadeLayers means you opt-in for the upcoming built-in usage of CSS cascade layers, it doesn't enable support for it, and you could already use it in userland anyway. Most users are more likely to turn v4: true globally, as we recommend, and they probably don't even care or know what CSS cascade layers is.

---

This kind of problem is likely going to be less important in the future once we remove that future flag, add built-in usage of CSS cascade layers

In V4 we want to change the default browserslist query to "baseline widely available": https://web.dev/blog/browserslist-supports-baseline

This means that CSS cascade layers will not downgrade anymore by default, even if you remove the config

It doesn't mean the same situation could happen again in the future for a new CSS feature, but it reduces the time for which it can happen in practice