Built-In CSS Support

Blitz allows you to import CSS files directly into any JavaScript file.

Adding a Global Stylesheet

To add a stylesheet to your application, import the CSS file within app/pages/_app.js.

For example, consider the following stylesheet named styles.css:

body {
  font-family: "SF Pro Text", "SF Pro Icons", "Helvetica Neue",
    "Helvetica", "Arial", sans-serif;
  padding: 20px 20px 60px;
  max-width: 680px;
  margin: 0 auto;
}

Then, import the styles.css file.

import "../styles.css"

export default function App({ Component, pageProps }) {
  return <Component {...pageProps} />
}

These styles (styles.css) will apply to all pages and components in your application. Due to the global nature of stylesheets, and to avoid conflicts, you may only import them inside _app.js.

In development, expressing stylesheets this way allows your styles to be hot reloaded as you edit them—meaning you can keep application state.

In production, all CSS files will be automatically concatenated into a single minified .css file.

Adding Component-Level CSS

Blitz supports CSS Modules using the [name].module.css file naming convention.

CSS Modules locally scope CSS by automatically creating a unique class name. This allows you to use the same CSS class name in different files without worrying about collisions.

This behavior makes CSS Modules the ideal way to include component-level CSS. CSS Module files can be imported anywhere in your application.

For example, consider a reusable Button component in the components/ folder:

First, create app/components/Button.module.css with the following content:

/*
You do not need to worry about .error {} colliding with any other `.css` or
`.module.css` files!
*/
.error {
  color: white;
  background-color: red;
}

Then, create app/components/Button.js, importing and using the above CSS file:

import styles from "./Button.module.css"

export function Button() {
  return (
    <button
      type="button"
      // Note how the "error" class is accessed as a property on the imported
      // `styles` object.
      className={styles.error}
    >
      Destroy
    </button>
  )
}

CSS Modules are an optional feature and are only enabled for files with the .module.css extension. Regular <link> stylesheets and global CSS files are still supported.

In production, all CSS Module files will be automatically concatenated into many minified and code-split .css files. These .css files represent hot execution paths in your application, ensuring the minimal amount of CSS is loaded for your application to paint.

Sass Support

Blitz allows you to import Sass using both the .scss and .sass extensions. You can use component-level Sass via CSS Modules and the .module.scss or .module.sass extension.

Before you can use Blitz' built-in Sass support, be sure to install sass:

npm install sass

Sass support has the same benefits and restrictions as the built-in CSS support detailed above.

Customizing Sass Options

If you want to configure the Sass compiler you can do so by using sassOptions in blitz.config.js.

For example to add includePaths:

const path = require("path")

module.exports = {
  sassOptions: {
    includePaths: [path.join(__dirname, "styles")],
  },
}

Less and Stylus Support

To support importing .less or .styl files you can use the following plugins:

If using the less plugin, don't forget to add a dependency on less as well, otherwise you'll see an error like:

Error: Cannot find module 'less'

TypeScript Support for CSS Modules

If you are using TypeScript and want typechecking and autocompletition for CSS Modules, you can install typescript-plugin-css-modules:

yarn add -D typescript-plugin-css-modules
# or
npm install -D typescript-plugin-css-modules

And add it to your tsconfig.json:

{
  "compilerOptions": {
+   "plugins": [{ "name": "typescript-plugin-css-modules" }]
  }
}

If you are having troubles using this plugin, check their documentation.