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

pnpm add -D nuxt-lightningcss

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

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

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

Configuration

To configure the module, add an options object with the lightningcss key:

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

  lightningcss: {
    // Options
  }
})

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

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

  /**
   * Lightningcss configuration object or path relative to nuxt rootDir
   * @default 'lightningcss.config.ts'
   */
  config?: Config | string
}

• 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 use a separate configuration file to define 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'))
})

Minification

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
  }
})

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
      }
    }
  }
})

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

Changelog

v2.3.0

compare changes

🚀 Enhancements

• Rely on vite exported lightningcss options (4860aa8)
• More robust way of handling global stylesheet, add source maps support (f0396d1)
• Resolve global stylesheets path from project root (2fdda76)
• Use extendViteConfig helper instead of extend:vite hook (6e0c71c)
• Watch lightningcss config file (9bf9018)

🩹 Fixes

• Build issues (a7d1983)

🏡 Chore

• Restore playground lightningcss configuration (43a0012)

❤️ Contributors

• Julien Dargelos [e-mail]