RFC: Global CSS Imports

[timneutkens]

Goals

• Allow dependencies (node_modules) to import .css files that are not CSS Modules
• Allow for automatic integration of libraries like react-spectrum which publish JS with CSS imports

Background

When CSS support was first introduced to Next.js, we added some restrictions and conventions to ensure CSS specificity and order would be preserved between compilations and output. These restrictions were added to avoid issues like certain CSS rules overriding each other.

In Next.js, every page is a separate entry point. Pages like pages/_app.js are also compiled and added to each page load, since it wraps every page. With webpack 4 the load order is important given that there's no module graph of relationships between entry points.

This is why we added the restriction of pages/_app.js being the only place you can import global CSS. With webpack 5, the module graph is now aware of which entry points depend on each other, allowing for CSS loading to be handled correctly.

We also tried to fix some features made possible by Create React App's handling of CSS. It's possible for a dependency to import global CSS, even though this is not valid JavaScript and can't run in the browser or Node.js environments. We've gotten feedback this restriction is not ideal for all libraries, given that some UI libraries include their own CSS imports (e.g. react-spectrum).

As of writing this RFC, there are multiple bundlers that have copied the behavior of Create React App with regards to handling CSS. More and more people have started depending on being able to import CSS in node_modules, making it harder for them to use these libraries with Next.js.

Related Issues and Discussions:

• Global CSS cannot be imported from within node_modules. #19936
• Allow importing global CSS inside of the pages/ directory, not just _app #20546
• Global CSS (import "tailwindcss/tailwind.css") shouldn't be importable in a layout component #21303
• can't import css from node_modules in lerna monorepo #19717
• Importing correctly scoped css from node_modules outside of _app #12079
• [9.3] CSS Modules cannot be imported from within node_modules #10975
• Support .css in node_modules (possibly using "next/dynamic") #25483
• Cannot import 3rd party css out of node_modules #25133
• Allow global css imports in well-behaved node_modules #25094

Note: We'll likely not add support for .module.css as we did not find packages using that. Please provide some examples and we'll have a look if it makes sense.

Proposal

In order to integrate these libraries into Next.js applications, we can remove the CSS imports restriction for both pages and node_modules when webpack 5 is used. This change would allow CSS to still be injected in the right order.

One issue that will arise from lifting this restriction is that CSS scoping will become an issue. Previously, you would end up getting guided to using scoped styles (CSS Modules) instead of global styles. This is not a concern for dependencies, as they tend to be published with their own scoped stylesheets.

Advantages

• It will allow libraries like react-spectrum and others to be used directly in Next.js without any additional configuration.
• It will allow users to import certain global CSS only on sections of an application. Do note that this could still lead to CSS specificity issues as when switching between pages existing styles could be around still, however based on the feedback we've had users that want this feature are fine with this trade-off.

[fabianishere]

To enable this behavior on the server, does this mean Next.js needs to process all imported dependencies through Webpack (similar to what next-transpile-modules does)? I can imagine that affecting the build performance if enabled by default.

[timneutkens]

No, we'd just no-op the .css imports using a require hook.

[agos]

regarding importing CSS modules from node_modules, the only way I see it useful is together with transpilation of code from node_modules, but even then it might not be worth it.

Example:

• I have two nextjs app that have a bunch of common components.
• To avoid repeating/copy pasting I create a small component library to use as dependency of those two apps.
• I then have to
  1. transpile all the components
  2. preprocess all my styles
  3. be able to import the style from the consuming app. This RFC currently covers point iii.

Transpiling+preprocessing ahead of distribution works fine (it's how all component library do it) BUT you lose all module structure and the build optimizations that could come with it.

The other current solution used for this kind of scenario is organising the project and this kind of dependencies in a monorepo, which I guess makes it hard to make the case for this kind of change

[kimgiutae]

Please, correct me if I'm wrong: currently the behaviour of next.js apps is loading all the css imported in _app.js, no matter if these styles are actually useful for the current/visible component/page?

[PsyGik]

Is this limited to only pages and node_modules, or can *.css|*.scss files be imported in components (non-page) as well?

[GrantGryczan]

I would really benefit from this.

[evgenymarkov]

My colleague recently made a workaround to make the @yandex/ui library work. Maybe this can help when designing a solution.

[parkerforrest]

This was super helpful, thank you! Got a library working for me.

[BossBele]

Worked for me

[AlbinoGeek]

./node_modules/@uiw/react-textarea-code-editor/lib/esm/style/index.css
Global CSS cannot be imported from within node_modules.
Read more: https://nextjs.org/docs/messages/css-npm
Location: node_modules/@uiw/react-textarea-code-editor/lib/esm/index.js

+1 on packages that require this.

[vjxDev]

Allow dependencies to import .css/.scss files in the same way CRA (import style globally). This will fix the "Global CSS cannot be imported from within node_modules." error.

Technically a feature request, but its related to this.
If you are going to be overhauling how CSS is managed in Next.js, why don`t you introduce a <Stylesheet> component. It can be used in components/pages for importing any style from the project or node_modules or even the web (url). This can get rid of "Global CSS cannot be imported from files other than your 'Custom <App>'" error.

// pages/home.js
import css from "../styles.css"
...
<Stylesheet src={css}/>

This will break backwards compatibility, so at start it can we limited to *.stylesheet.css and maybe styles from 'node_modules'.

New features this can bring to the Next.js framework.

This can introduce new features like allowing css to be global or scoped to a component/page. Scoped styles can be imported (injected as a link or style tag ) when a component is rendered. Possibly allow for dynamic importing of css?

Inlining of some or all global css to reduce Cumulative Layout Shift and allow for this effect #12868 (reply in thread) .This can even be useful for something like AMP/hybrid pages where all css can be inlined into <style amp-custom>.

You can even introduce ordering of css in the document. This can be useful if you are using something like tailwindcss where @tailwind base must be at the start, and @tailwind utilities must be at the end of styles.

// components/Button.js
import css from "../styles/button.stylesheet.css"
...
<Stylesheet scoped order={2} src={css}/>

// pages/_app.js  or pages/hello.js
import base from "../styles/base.stylesheet.css"
import utils from "../styles/utils.stylesheet.css"
const Button = dynamic(import('../components/Button'))'
...
<Stylesheet global inline order={1} src={base }/>
<Stylesheet global order={3} src={utils}/>
<Button />

Css order in the document

1. node_module global styles
2. Ordered <Stylesheet/> styles
   2.1 base.stylesheet.css inlined
   2.2 button.stylesheet.css, and other styles with order of 2
   2.3 utils.stylesheet.css
3. styled-jsx? and css module styles? ( I'm not suggesting to remove css modules. )

Css imported by dependencies in node_module can be placed before all the <Stylesheet/> component styles. I don`t know how styled-jsx and css modules will get ordered, probably after everything.

Alternatives

I know that styled-jsx exits, but it has limitations like no first party support for scss/postcss. And plugins like styled-jsx-plugin-postcss don`t have HMR which leads to a bad dev experience. If you use tailwind with styled-jsx-plugin-postcss, change some file and add some new JIT style, you need to 1st save the component with the <style jsx> and then manually refresh the page to see cahges.

[AlbinoGeek]

What about styled-components? That's my go to library, it supports global styles, and it works incredibly well with the next js, including using full SSR and SSG. You can even do per components dynamic imports exactly as you described. I would suggest having a look at what they implemented, and perhaps taking a few pointers from there at least when it comes to developer friendliness.

…

On Tue., Aug. 31, 2021, 5:12 p.m. Jovica Veljković, < ***@***.***> wrote: Allow dependencies to import .css/.scss files in the same way CRA (import style globally). This will fix the "Global CSS cannot be imported from within node_modules." error. Technically a feature request, but its related to this. If you are going to be overhauling how CSS is managed in Next.js, why don`t you introduce a <Stylesheet> component. It can be used in components/pages for importing any style from the project or node_modules or even the web (url). This can get rid of "Global CSS cannot be imported from files other than your 'Custom <App>'" error. // pages/home.jsimport css from "../styles.css" ...<Stylesheet src={css}/> This will break backwards compatibility, so at start it can we limited to *.stylesheet.css and maybe styles from 'node_modules'. New features this can bring to the Next.js framework. This can introduce new features like allowing css to be global or scoped to a component/page. Scoped styles can be imported (injected as a link or style tag ) when a component is rendered. Possibly allow for dynamic importing of css? Inlining of some or all global css to reduce Cumulative Layout Shift and allow for this effect #12868 (reply in thread) <#12868 (reply in thread)> .This can even be useful for something like AMP/hybrid pages where all css can be inlined into <style amp-custom>. You can even introduce ordering of css in the document. This can be useful if you are using something like tailwindcss where @tailwind base must be at the start, and @tailwind utilities must be at the end of styles. // components/Button.jsimport css from "../styles/button.stylesheet.css" ...<Stylesheet scoped order={2} src={css}/> // pages/_app.js or pages/hello.jsimport base from "../styles/base.stylesheet.css"import utils from "../styles/utils.stylesheet.css"const Button = dynamic(import('../components/Button'))' ... <Stylesheet global inline order={1} src={base }/> <Stylesheet global order={3} src={utils}/> <Button /> Css order in the document 1. node_module global styles 2. Ordered <Stylesheet/> styles 2.1 base.stylesheet.css inlined 2.2 button.stylesheet.css, and other styles with order of 2 2.3 utils.stylesheet.css 3. styled-jsx? and css module styles? ( I'm not suggesting to remove css modules. ) Css imported by dependencies in node_module can be placed before all the <Stylesheet/> component styles. I don`t know how styled-jsx and css modules will get ordered, probably after everything. Alternatives I know that styled-jsx exits, but it has limitations like no first party support for scss/postcss. And plugins like styled-jsx-plugin-postcss don`t have HMR which leads to a bad dev experience. If you use tailwind with styled-jsx-plugin-postcss, change some file and add some new JIT style, you need to 1st save the component with the <style jsx> and then manually refresh the page to see cahges. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#27953 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAOSNPLQLQK4HHJX257UAC3T7VVXPANCNFSM5B57QDTA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[vjxDev]

Styled components and emotion are CSS in JS and have the down side of longer paring time, increasing the time to interactivity and lowering the light house score.

I stopped using Material UI because emotin js was increasing iit

[AlbinoGeek]

By my use case (full SSG) there is almost zero overhead between using styled-components versus hard-including a .css file in the App (which is the alternative. Our application needs to able to manipulate the entire stylesheet (not just CSS vars) for themes that modify the layout, so we could not use a CSS system which wouldn't allow for re-usable and extendable blocks of CSS with transformations.)

However, heavily use-case dependent as stated. I feel v5 has made things really comparable to CSS-only systems (in Benchmarks on the client, where the server pre-renders CSS in _document)

Not disagreeing so much as showing a use-case where it has very little overhead. *

[kimgiutae]

I also likes the CSS-in-JS approach. It helps to keeps everything in TSX.

To solves the load/parsing issue, some new libs like https://github.com/callstack/linaria has the same functionallity as styled-components but parsed at build-time. It's zero-runtime CSS-in-JS, CSS is extracted to CSS files during build.

Also... sadly the development of SC seems a little slow lately...

[blvdmitry]

This is a so long-awaited improvement for me. I've got two libraries that are working in a way similar to react-spectrum, where pre-building CSS into a single bundle is not an option as that defeats the purpose of tree-shaking of styles. CSS Modules support with next-transpile-modules support and indeed the last thing that's currently blocking this is support of styles for tag elements.

In the description you cover the part about importing the non css modules files. Does that mean that we'll need to move all global styles to a separate file? Currently we're storing them together with other styles in .module.css but this small trade-off shouldn't be causing any tough issues as I see it for the libraries anyways.

[lunelson]

I hope that this would allow global Sass imports as well as CSS—unlike the current allowance for global CSS imports in _app.js, which is restricted to *.css files—since it's a common feature of Sass libraries that they are configurable through injection of the additionaData and/or custom importer option(s) in sass-loader, it would thus be limiting to assume that dependency global style imports are pre-flattened to CSS

[yantakus]

We decided to move separate next.js repos into a monorepo and this issue is a blocker in our case. Any updates on this? Thanks.

[natterstefan]

Hi @leerob, hi, @timneutkens,

this is still blocking us from using Cypress' component testing feature (cypress-io/cypress#16879) at the moment. Any updates on this?

Thanks for taking care of this.

[pooyarm]

This would also help us to be able to always use the latest nextjs version. Currently we're importing LESS files globally (on each component) since we have hundreds of components, we can't easily refactor all of them to use css modules. So the restriction of importing global styles is holding us back from using the latest nextjs. I've described more here #29693

Any update on this topic?

[stopyransky]

Just a heads up that above is the issue for @nrwl/nx monorepos with next.js app + shared-ui library (as example).

[pooyarm]

why can't be a generic topic? I think having it globally would be more helpful than harmful.

[pascuflow]

Was brought here after googling "Global CSS cannot be imported from within node_modules", any workaround in my control to fix this?

[marek-hanzal]

And how about importing SVGs from CSS in node_modules? I'm trying to use antd-mobile and this thing makes me a lot of pain...

[xyy94813]

next-global-css not working for me ...

In next@12.1.0

const withPlugins = require('next-compose-plugins')
const { patchWebpackConfig } = require('next-global-css')
const webpackNodeExternals = require('webpack-node-externals')

module.exports = withPlugins([], {
  webpack(config, options) {
     patchWebpackConfig(config, options)

      if (options.isServer) {
        config.externals = webpackNodeExternals({
          // Uses list to add this modules for server bundle and process.
          allowlist: [/antd/],
        })
      }
  }
})
     

[medihack]

It also doesn't work for me with next@12.1.4. I opened an issue over there.

[alebelcor]

Until it's baked in I use "next-transpile-modules" as a workaround for global CSS imports from node_modules.

The feature is advertised here, down below.

[shifengdiy]

is it worked in less file ?

[cseas]

Is there a recommended workaround for now while this RFC gets discussed?
This issue is a blocker for moving our project to Next.js.

[benkingcode]

See #27953 (reply in thread)

[VadimGut]

The solution I temporary implemented was actually by passing the import issue by loading the file as a string
I wrote a postprocess.js file which build a clean short version of the style.css
and i load it inside the _document.js like so

  static async getInitialProps(ctx) {
    const globalStyle = await fs.readFileSync(path.join(__dirname, 'path/to/style.css'));
    const initialProps = await Document.getInitialProps(ctx)
    return {
      ...initialProps,
      styles: (
        <>
          {initialProps.styles}
          <style dangerouslySetInnerHTML={{
            __html: `${globalStyle}`
          }}/>
        </>
      )
    }
  }

[brianjenkins94]

So if I wanted to load a different global stylesheet depending on the page, I could put that logic here?

And this would inline that stylesheet and only that stylesheet?

[VadimGut]

Yup
This would be a dirty work around but it is possible

[YGKtech]

Is there a good reason this hasn't been acted on yet? I don't see any significant counter-arguments in the thread, just a lot of suggestions and people seeking workarounds because nothing has been done yet.

I'd appreciate it if someone could add a warning and some official guidance on the topic to the documentation, so users can at least be aware of this tripping point without having to drag through a bunch of years-old github threads.

It's a severe limitation for Next to just be incompatible with a bunch of libraries that every other major build stack can use. I reviewed the official docs and migration guides carefully before deciding to migrate from CRA, yet the first I learned of this issue was several hours into the process when the build stack started choking on a dependency I cannot replace right now.

In fact, the FAQ's boast about NextJS' compatibility with 3rd party libraries:
Can I use Next.js with my favorite JavaScript library?
Yes! We have hundreds of examples in our examples directory
^ this would be a great place to mention that there's actually widespread compatibility issues, rather than claiming the contrary

I'm not currently paying for this software, so I know I'm not entitled to much, but I would ask that I not be actively misled.

[leerob]

We’re exploring if a solution to this RFC could be implemented with the Layouts RFC, since they have related pieces (for example, the root layout would replace _app.js).

We will post back here as we learn more 👍🏼

[brianjenkins94]

As long as it works with Static HTML export. 🤞

Gotta wait for the sequel to the Layouts RFC blog post to learn about what portions of the new Layouts RFC are going to work with Static HTML export.

I'm no expert but React Server Components sound like they'll inextricably require a server.

Hopefully I'm wrong :)

[leerob]

The Layouts RFC will be compatible with next export.

[msdrigg]

I know you don't need someone else saying adding a +1 to the discussion, but this is a major pain point. I'm at the point where I can't un-port my project and this issue is holding me back from using several dependencies that would be very useful to me.

Can we allow this behind a configuration flag that is default off? There are no viable work-arounds right now that work with the current next stack (swc), and this is causing a lot of frustration.

[agusterodin]

If you want a temporary solution and only have this issue with a couple of your libraries, you can manually write a couple overrides that will remove the offending CSS import lines.

Sorta unrelated but here is an example of an override I apply to the leaflet library to avoid a autoprefixer error. You could write a similar type of override script that removes any import lines that contain generic regex for "import "bla.css".

const fs = require('fs')

// Fixes autoprefixer replace color-adjust to print-color-adjust, color-adjust shorthand is currently deprecated warning.
// No current way to specify files to ignore in autoprefixer.

try {
  const sourceCode = fs.readFileSync('node_modules/leaflet/dist/leaflet.css', 'utf8')
  const sourceCodeSplittedAtOffendingLine = sourceCode.split('/* Printing */')
  if (sourceCodeSplittedAtOffendingLine.length === 2) {
    fs.writeFileSync('node_modules/leaflet/dist/leaflet.css', sourceCodeSplittedAtOffendingLine[0], {
      encoding: 'utf8',
      flag: 'w'
    })
    console.log('leaflet css issue fix was applied')
  }
}
catch {
  console.warn('leaflet css issue fix failed (file operation error)')
  process.exit(0)
}

You can have your overrides apply automatically after install by adding this to package.json scripts:

"postinstall": "node ./carbon-lib-ui/configurations/overrides.js"

[agusterodin]

It sure beats being stuck on Create React App in my opinion!

[msdrigg]

I appreciate you sharing this. I'll take a look at making this work. The process is still frustrating, but you are right, some workaround is definitely better than none. :)

[agusterodin]

You should be able to whip it up in about an hour. A generic "delete any line with import bla .css in it" function that takes a handpicked array of file paths should do the trick.

Be sure to delete your .next folder if the issue persists even after the overrides are applied (during development of your overrides). If you don't, Next may be using a cached version that it compiled and you will still see the errors!

[anavgagneja]

There's a plugin that does this for you :) https://www.npmjs.com/package/next-remove-imports

[ScriptedAlchemy]

This would help quite a lot. Using next transpile modules substantially increases build time.

I’ve been working around this by compiling all my libraries with a modified css plugin. So css (local scope or not) in library’s are emitted as

export const locals {}
Export default “css string”

then I use mini-css loader and train it to test css.js files which it already knows that locals is locally scopes styles and default is the string of css. Basically feeding it what css-loader would, but I ship this in my packages to circumvent nexts limitations.

[leerob]

Slight update here from 12.3 post:

Additionally, in a different RFC, we're exploring adding support for Global CSS Imports in the new app directory . This would allow you to use packages that import their own .css files without additional configuration.

We are exploring this with the upcoming changes!

[ScriptedAlchemy]

So if I move to the new app folder I can use global css throughout my components?

In my case, my component library ships css modules, but next sees it as global css because it was already processed during library build.

Honestly support for css would speed up my build times a huge amount. Literally the entire company has to use next transpile modules for anything we author. It takes minutes to get a dev build up. It kill's because i use next for everything and it's lightning fast on even my larger projects. But at lulu the transpile of over 3000 modules that don't need any additional transpilation destroys build perf.

Outside lulu, with some tweaks to node's IO - a cold prod build averages 3 seconds. If I apply those tweaks to node at lulu, it takes about 40% off compile time - but it's still extremely slow

My workaround of shipping css files as JS exports that mini css understands works, but it's tricky to pivot the whole company onto a build pipeline that supports this specific scenario. We have to configure our builds and consumer builds specifically for use at lululemon. If it's not on our build chain, it won't work since it's a weird middle state where it's not css and not JS that we ship to npm.

The global css issue has been the top problem for us. We have had to drastically alter next Webpack configuration to support the company.

Over 1,000 lines of next.config customizations. A lot is around process of images, assets, fonts, css that come from our libraries.

Might seem like a "small" change - but this is my top problem with next.js and the workarounds we must do cause very visible business impacts and DX degradation.

[gaithoben]

I am watching this issue as well. Its such a huge block on my way!

[tobzy]

Watching this as well.

[felipenmoura]

This is indeed, very frustrating.
You select the right package to use to solve a given problem and install it, only to find out "next doesn't support it".
How come?

I really like next.js but this framework should be way, WAY less opinionated on how people can work.
Offering support for good practices is one thing, limit which packages we can or cannot use based on the time/interest of third party developers is a no-go.

Looking forward to seeing this update 😄
For now...I'll have to rely on packages that were not my "first option" 😞

[leerob]

Update: We’re excited to announce Next.js 13, which includes the new app/ directory (beta) with support for nested layouts, colocation of data fetching, streaming, Server Components by default, and much more. Further, you can use packages that import their own .css files without additional configuration.

Inside the app/ directory, CSS files can now be imported inside any layout or page, including styles from external npm packages. This solves the original proposal in this RFC.

[linus-jansson]

Why cant this also be part of the pages directory until appDir become stable? I am unable to use appDir in my work because of the experimental part of the appDir.. :/

[Jairwin-L]

can support less? Very much hope to support, many developers are also like to use less. #45169

my English isn‘t good

[Atrus619]

looking for less support here as well

[zatarain]

I am still looking for less support too :(

[ohare93]

Same here

[twinsant]

OK. Still blocked when I use Monaco Editor.

[mrcampbell]

Came to say the same!

[timneutkens]

When using app?

[chaitanya71998]

@twinsant any update how you solved this issue, i was facing an issue with monaco editor like below when using in next js.
I am using monaco lanugage client to create a language client server integration

import Editor from "@monaco-editor/react"
import * as monaco from "monaco-editor/esm/vs/editor/editor.api"
import { CloseAction, ErrorAction, MessageTransports, MonacoLanguageClient } from "monaco-languageclient"
import { WebSocketMessageReader, WebSocketMessageWriter, toSocket } from "vscode-ws-jsonrpc"
function createLanguageClient(transports: MessageTransports) {
	let client = new MonacoLanguageClient({
		name: "Sample Language Client",
		clientOptions: {
			// use a language id as a document selector
			documentSelector: ["java"],
			// disable the default error handler
			errorHandler: {
				error: () => ({ action: ErrorAction.Continue }),
				closed: () => ({ action: CloseAction.DoNotRestart }),
			},
		},
		// create a language client connection from the JSON RPC connection on demand
		connectionProvider: {
			get: () => {
				return Promise.resolve(transports)
			},
		},
	})
}
...  so on editor code

[akhilalekha]

Hey @twinsant @chaitanya71998 found any solution for this ?

[medihack]

@akhilalekha Not sure if it helps, but I am using the below custom Webpack config code in my next.config.js (without enabled app feature). Works for me with Next.js v13.2.1 and Monaco v0.36.0.

    config.module?.rules
      .find((rule) => rule.oneOf)
      .oneOf.forEach((rule) => {
        if (rule.issuer?.and?.[0]?.toString().includes("_app")) {
          const and = rule.issuer.and
          rule.issuer.or = [/[\\/]node_modules[\\/]monaco-editor[\\/]/, { and }]
          delete rule.issuer.and
        }
      })

[leerob]

Following up on this: the App Router is now stable with 13.4!

CSS files can now be imported inside any layout or page, including styles from external npm packages.

https://nextjs.org/blog/next-13-4