[RFC] CSS Support

[Timer]

Goals

• Support global CSS effects (e.g. Bootstrap, Normalize.css, UX-provided, etc)
• Support stable component-level CSS
• Hot-reload style changes in development (no page refresh or state loss)
• Able to code-split for critical CSS extraction in production
• Leverage existing convention users are already familiar with (e.g. Create React App)
• Retain existing styled-jsx support, potentially more optimized

Background

Importing CSS into JavaScript applications is a practice popularized by modern day bundlers like Webpack.

However, it's tricky to get CSS imports right: unlike JavaScript, all CSS is globally scoped. This means it does not lend itself well to bundling. Especially bundling between multiple pages where styling is separated in a CSS file per page and load order matters.

By our measurements, more than 50% of Next.js users use Webpack to bundle .css files, either through @zeit/next-css, @zeit/next-sass, @zeit/next-less, or a custom setup. This is further verified through talking to companies. Some have all their styles through importing CSS, others use it for global styles and then use a CSS-in-JS solution to style components.

Currently we have these three plugins that allow you to import CSS, however, they have common issue in CSS ordering and certain loading issues. The reason for this is that @zeit/next-css doesn't enforce a convention for global styles. Global CSS can be imported in every component / JavaScript file in the project.

To solve these common issues and make it easier for users to import CSS we're planning to introduce built-in support for CSS imports. This will be similar to styled-jsx where if you don't use the feature there will be no built-time or runtime overhead.

This effort also allows us to improve developer experience of the solution.

Proposal

Next.js should support modern CSS and down-level it on behalf of the user. This approach would be similar to how we support modern JavaScript and compile it down to ES5.

By default, we should:

• Use Autoprefixer to add vendor-specific prefixes automatically (without legacy flexbox support)
• Polyfill or compile Stage 3+ CSS features with their equivalents
• Automatically fix known "flexbugs" for the user

During development, CSS edits should be automatically applied, similar to JavaScript hot reloading.

In production, all CSS should be fully extracted from the JavaScript bundle(s) and emitted into .css files.

Furthermore, this .css should be code-split (when possible) so that only the critical-path CSS is downloaded on page load.

Global CSS

Next.js will only allow you to import Global CSS within a custom pages/_app.js.

This is a very important distinction (and a design flaw in other frameworks), as allowing Global CSS to be imported anywhere in your application means nothing could be code-split due to the cascading nature of CSS.

This is an intentional constraint. Because when global CSS is imported in for example, a component, it will behave different when moving from one page to another.

Usage Example

/* styles.css */
.red-text {
  color: red;
}

// pages/_app.js
import '../styles.css'

export default () => <p className="red-text">Hello, with red text!</p>

Component-level CSS

Next.js will allow pure CSS Modules to be used anywhere in your application.

Component-level CSS must follow the convention of naming the CSS file .module.css to indicate its intention to be used with the CSS Modules specification.

The :global() CSS Modules specifier is allowed when combined with a local class name, e.g. .foo :global(.bar) { ... }.

Usage Example

/* components/button.module.css */
.btnLarge {
  padding: 2rem 1rem;
  font-size: 1.25rem;
}

.foo :global(.bar) {
  /* this is allowed as an escape hatch */
  /* (useful when controlling 3rd party libraries) */
}

:global(.evil) {
  /* this is not allowed */
}

/* components/button.js */
import { btnLarge } from './button.module.css'

// import '../styles.css'; // <-- this would be an error

export function Button({ large = false, children }) {
  return (
    <button
      className={
        large
          ? // Imported from `button.module.css`: a unique class name (string).
            btnLarge
          : ''
      }
    >
      {children}
    </button>
  )
}

[alejalapeno]

I'm guessing with plugins like @zeit/next-sass already working with the current supported flavor of CSS Modules that .module.scss would also work? Or does the phrase "pure CSS Modules" mean only .module.css?

Sass support is make it or break it for most projects to me.

[timneutkens]

The @zeit/next-css/sass/less/stylus plugins will be deprecated in favor of this RFC (built-in support). We're still discussing to what extent sass will be part of the core vs a plugin. My current thinking is when you add node-sass it'll enable sass support. Similar to what we do for TypeScript. The reason we won't add it as a dependency is that it's quite large and very slow to install because of native bindings etc.

[zen0wu]

This is exciting! I was tripped by conflicting css class names just as today!

Question, how does it work with TypeScript? One reason that I haven't enabled css-module is that, importing css module would give an any object (maybe a bit magical, like .foo-bar will be become a field called fooBar?), which is not TS friendly. Since Next is now TS by default, I would imagine we can do better in this matter?

[TheHolyWaffle]

I'm not sure if "Automatically fix known flexbugs for the user" is going to be a good idea.

I fear that we'll end in confusing scenarios where third party component libraries on npm, that include css stylesheets, will behave differently in nextjs environments than in others (such as create-react-app).

[Timer]

@TheHolyWaffle fixing known flexbugs creates a more predictable behavior -- and is also what Create React App does.

[Timer]

@ZenoZen Per the CSS Modules specification, it does not do anything fancy to camelcase for you. If you use class names with a dash (class-name) you'd need to explicitly access that on the object.

e.g.

import Everything from './file.module.css'

// later on

Everything['class-name']

As for TS, we don't plan any magic to handle the types but it's pretty easy to define a TS type to handle these files.

declare module '*.module.css' {
  const classes: { readonly [key: string]: string };
  export default classes;
}

declare module '*.module.scss' {
  const classes: { readonly [key: string]: string };
  export default classes;
}

declare module '*.module.sass' {
  const classes: { readonly [key: string]: string };
  export default classes;
}

[adamwathan]

Whatever we do here can we make sure it's still easy to use custom PostCSS plugins like it is now with @zeit/next-css? It would be a real shame if we lost support for that — CRA doesn't support this and because of that it's impossible to use tools like Tailwind CSS in any sort of reasonable way.

I would be careful about these three features in this regard:

• Use Autoprefixer to add vendor-specific prefixes automatically (without legacy flexbox support)
• Polyfill or compile Stage 3+ CSS features with their equivalents
• Automatically fix known "flexbugs" for the user

...because this is all done with PostCSS, and it's very important that PostCSS plugin order be under the end-user's control.

I would suggest that if you are going to enable those three plugins by default, that the user should be able to completely override the default PostCSS config by providing their own postcss.config.js file. They would have to add those plugins manually if they went this route, but that level of control is necessary in my opinion.

TL;DR please be careful not to break the ability for users to have complete control of PostCSS, I literally can't use CRA because of this and I would be very sad if I couldn't use Next anymore.

[jescalan]

Seconding @adamwathan - would be great to get more detail here on how postcss option customization would look. It would be really great to have an option to modify postcss config via next plugin as well as postcss.config.js, so that configs shared across multiple projects can be easily injected without an extra file.

[felixmosh]

I think that it is better to enable css modules for all css imports (not only for .module suffix), and the one that we want to be global we will need to specify a .global suffix.

[jamsch]

CSS Modules would be great. I think keeping the *.module.(css|scss) spec is fine as it does align with create-react-app, allow for typescript typings, and allow for easier migrations for other users new to Next.js

With typescript, you can enforce CSS module typings by generating *.d.ts typings for every *.(css|scss) file using typed-css-modules and typed-scss-modules but if you don't want to do that and still want autocompletion, you can use the following VS Code extension:
https://marketplace.visualstudio.com/items?itemName=clinyong.vscode-css-modules

[Timer]

@adamwathan rest assured we'll be allowing PostCSS configuration! We're not sure how the exact implementation will look like yet, but it should emerge naturally with the CSS pull request.