nuxt-lightningcss

nuxt-lightningcss

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

• 📖  Lightningcss documentation
• ✨  Release Notes

Quick Setup

• Add nuxt-lightningcss dependency to your project

# Using pnpm
pnpm add -D nuxt-lightningcss

# Using yarn
yarn add --dev nuxt-lightningcss

# Using npm
npm install --save-dev 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 lightningcss, 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
    }]
  ]
})

This module takes the same options as those from the lightningcss transform function, except for the following:

• code
• filename
• projectRoot
• analyzeDependencies
• sourceMap
• inputSourceMap
• cssModules

It also provides these extra options:

• globals: an array of stylesheet paths to import in all other stylesheets. This is especially useful when you want to precompile custom media queries.

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 module options:

import { browserslistToTargets } from 'lightningcss'
import browserslist from 'browserslist'

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

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

Custom media queries

Custom media queries can be precompiled using lightningcss, but since they are replaced with the actual queries, 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: [
      '~/assets/stylesheets/media-queries.css' // Import your custom media queries in all stylesheets
    ],
    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
yarn install

# Generate type stubs
yarn dev:prepare

# Develop with the playground
yarn dev

# Build the playground
yarn dev:build

# Run ESLint
yarn lint

# Run Vitest
yarn test
yarn test:watch

# Release new version
yarn release