nuxt-lightningcss

Use the built-in lightningcss preprocessor of Vite with Nuxt.

Quick Setup

Add nuxt-lightningcss dependency to your project

pnpm add -D nuxt-lightningcss

Add nuxt-lightningcss to the modules section of nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    'nuxt-lightningcss'
  ]
})

To get the proper syntax highlighting in your components, use lang="postcss" in your style tags:

<style lang="postcss">
  .a {
    color: black;

    .b {
      color: blue;
    }
  }
</style>

That's it! You can now use lightningcss in your Nuxt app ✨

Configuration

To configure the module, add an options object either with the lightningcss key or in the modules array:

export default defineNuxtConfig({
  modules: [
    'nuxt-lightningcss'
  ],

  lightningcss: {
    // Options
  }
})

export default defineNuxtConfig({
  modules: [
    ['nuxt-lightningcss', {
      // Options
    }]
  ]
})

export interface ModuleOptions {
  /**
   * Paths to global stylesheets
   * @default undefined
   */
  globals?: string[] | undefined

  /**
   * Wether to minify stylesheets
   * @default true
   */
  minify: boolean

  /**
   * Lightningcss configuration file or object
   * @default '~~/lightningcss.config.ts'
   */
  config: string | Config
}

globals: an array of stylesheet paths to import in all other stylesheets. This is especially useful when you want to transpile custom media queries.
minify: set to false to disable lightningcss minification (always disabled in development mode)
config: lightningcss configuration file or object. By default, the module will look for a lightningcss.config.ts file in the root of your project.

Configuration file

You can create a file to set lightningcss configuration:

// ~~/lightningcss.config.ts

import { defineLightningCSSConfig } from 'nuxt-lightningcss'

export default defineLightningCSSConfig({
  // Lightningcss configuration
})

Targets

The lightningcss targets option is automatically set from you project browserslist configuration (either in .browserslistrc, browserslist, package.json or in the BROWSERSLIST environment variable). If there isn't an explicit browserslist configuration in your project, the defaults preset will be used. This can also be overridden from the lightningcss configuration:

import { defineLightningCSSConfig } from 'nuxt-lightningcss'
import { browserslistToTargets } from 'lightningcss'
import browserslist from 'browserslist'

export default defineLightningCSSConfig({
  targets: browserslistToTargets(browserslist('> 0.5%, last 2 versions, Firefox ESR, not dead'))
})

Custom media queries

Custom media queries can be transpiled using lightningcss, but since their actual definition is removed from the bundled stylesheets, they need to be imported in all stylesheets that use them. You can do that using the following configuration:

import { Features } from 'lightningcss'

export default defineNuxtConfig({
  modules: [
    'nuxt-lightningcss'
  ],

  lightningcss: {
    globals: [
      // Import your custom media queries in all stylesheets
      '~/assets/stylesheets/media-queries.css'
    ],
    config: {
      include: Features.CustomMediaQueries,
      drafts: {
        customMedia: true
      }
    }
  }
})

Minify

By default, stylesheets are minified in production using lightningcss. You can disable minification using the following configuration (always disabled in development mode):

import { Features } from 'lightningcss'

export default defineNuxtConfig({
  modules: [
    'nuxt-lightningcss'
  ],

  lightningcss: {
    minify: false
  }
})

Development

# Install dependencies
pnpm install

# Generate type stubs
pnpm dev:prepare

# Develop with the playground
pnpm dev

# Build the playground
pnpm dev:build

# Run ESLint
pnpm lint

# Run Vitest
pnpm test
pnpm test:watch

# Release new version
pnpm release