CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-nuxt--vite-builder

Vite bundler for Nuxt applications providing seamless integration between Nuxt's framework and Vite's build system

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

css-processing.mddocs/

CSS Processing

PostCSS integration and CSS handling for both development and production builds, including plugin configuration and style optimization.

Capabilities

CSS Options Resolution

Resolves and configures CSS processing options including PostCSS plugins based on Nuxt configuration.

/**
 * Resolve CSS processing options including PostCSS plugins
 * Loads and configures PostCSS plugins from Nuxt configuration
 * @param nuxt - Nuxt instance with PostCSS configuration
 * @returns Promise resolving to Vite CSS configuration object
 */
function resolveCSSOptions(nuxt: Nuxt): Promise<ViteConfig['css']>;

Usage Example:

import { resolveCSSOptions } from "@nuxt/vite-builder/css";
import type { Nuxt } from "@nuxt/schema";

// Resolve CSS options from Nuxt configuration
const cssConfig = await resolveCSSOptions(nuxt);

// The returned config includes:
// - PostCSS plugins configuration
// - CSS preprocessing options  
// - Development sourcemap settings

PostCSS Plugin Configuration

Automatically loads and configures PostCSS plugins based on Nuxt's postcss configuration.

/**
 * PostCSS configuration structure for Vite
 */
interface PostCSSConfig {
  /** Array of configured PostCSS plugins */
  plugins: Plugin[];
}

/**
 * PostCSS plugin sorting function
 * @param config - PostCSS configuration with plugins and order
 * @returns Sorted array of plugin names
 */
function sortPlugins(config: { 
  plugins: Record<string, any>; 
  order?: string[] | ((names: string[]) => string[]); 
}): string[];

Plugin Loading Process:

// PostCSS plugins are loaded from Nuxt configuration
// Example nuxt.config.ts
export default defineNuxtConfig({
  postcss: {
    plugins: {
      'autoprefixer': {},
      'cssnano': {
        preset: 'default'
      },
      'tailwindcss': {}
    },
    order: ['tailwindcss', 'autoprefixer', 'cssnano']
  }
});

Plugin Resolution

Dynamically loads PostCSS plugins from the module system with proper error handling.

Plugin Loading Features:

  • Module Resolution: Attempts to load plugins from multiple module directories
  • Error Handling: Provides clear error messages for missing plugins
  • Configuration Passing: Passes plugin-specific configuration options
  • Order Management: Respects plugin execution order
// Plugin loading example (internal process)
for (const pluginName of sortPlugins(postcssOptions)) {
  const pluginOptions = postcssOptions.plugins[pluginName];
  if (!pluginOptions) continue;

  // Attempt to load plugin from various module directories
  for (const parentURL of nuxt.options.modulesDir) {
    const pluginFn = await jiti.import(pluginName, { 
      parentURL: parentURL.replace(/\/node_modules\/?$/, ''), 
      try: true, 
      default: true 
    });
    
    if (typeof pluginFn === 'function') {
      css.postcss.plugins.push(pluginFn(pluginOptions));
      break;
    }
  }
}

Built-in CSS Support

The CSS processing system includes support for various CSS preprocessors and features.

Supported CSS Features:

  • Native CSS: Standard CSS with PostCSS processing
  • SCSS/Sass: Sass preprocessing with variable support
  • Less: Less preprocessing and compilation
  • Stylus: Stylus preprocessing support
  • PostCSS: Full PostCSS plugin ecosystem
  • CSS Modules: Scoped CSS with module support

Development Sourcemaps

CSS sourcemap configuration for development debugging.

// CSS sourcemap configuration
const cssConfig = {
  devSourcemap: !!nuxt.options.sourcemap.client, // Client sourcemaps
  // Server-side CSS processing also respects server sourcemap settings
};

Sourcemap Features:

  • Original Source Mapping: Maps compiled CSS back to original source files
  • Preprocessor Support: Sourcemaps work with Sass, Less, and Stylus
  • PostCSS Integration: Maintains sourcemaps through PostCSS transformations
  • Development Only: Sourcemaps are typically disabled in production

CSS Extraction and Inlining

Advanced CSS handling for production builds with extraction and inlining capabilities.

/**
 * SSR styles plugin options for CSS extraction
 */
interface SSRStylesPluginOptions {
  /** Source directory for relative path resolution */
  srcDir: string;
  /** Set of chunk IDs that should have inlined CSS */
  chunksWithInlinedCSS: Set<string>;
  /** Function or boolean determining CSS inlining strategy */
  shouldInline?: ((id?: string) => boolean) | boolean;
  /** Component definitions for CSS extraction */
  components: Component[];
  /** Mapping of CSS files to client chunks */
  clientCSSMap: Record<string, Set<string>>;
  /** Application entry point */
  entry: string;
  /** Global CSS file paths */
  globalCSS: string[];
  /** Build mode: server or client */
  mode: 'server' | 'client';
}

CSS Optimization

Production CSS optimization including minification and purging.

Optimization Features:

  • Minification: CSS minification via cssnano or similar
  • Purging: Unused CSS removal (when configured)
  • Autoprefixing: Automatic vendor prefix addition
  • Critical CSS: Critical CSS extraction for above-the-fold content
  • CSS Splitting: Automatic CSS code splitting by route

CSS-in-JS Support

Support for CSS-in-JS solutions commonly used with Vue.js.

Supported CSS-in-JS:

  • Vue SFC Styles: Scoped and module styles in Single File Components
  • CSS Modules: Automatic CSS module processing
  • Styled Components: Integration with styled-components (via plugins)
  • Emotion: Support for Emotion CSS-in-JS (via plugins)

Global CSS Handling

Management of global CSS files and their injection into the build.

// Global CSS configuration
const globalCSS = [
  '~/assets/css/main.css',
  '~/assets/scss/variables.scss',
  '@/styles/global.css'
];

// These files are:
// 1. Processed through PostCSS
// 2. Injected into the application
// 3. Available across all components

CSS Asset Management

Handling of CSS-related assets like fonts, images, and other resources.

Asset Processing:

  • URL Resolution: Resolves relative URLs in CSS files
  • Asset Optimization: Optimizes images and fonts referenced in CSS
  • Public Asset Integration: Handles assets from public directories
  • CDN Integration: Supports CDN URLs for external assets

Error Handling

Comprehensive error handling for CSS processing issues.

Error Types Handled:

  • Plugin Loading Errors: Clear messages for missing PostCSS plugins
  • Syntax Errors: Detailed CSS/Sass/Less syntax error reporting
  • Asset Resolution Errors: Helpful messages for missing CSS assets
  • Configuration Errors: Validation of PostCSS configuration
// Error handling example
if (typeof pluginFn !== 'function') {
  console.warn(`[nuxt] could not import postcss plugin \`${pluginName}\`. Please report this as a bug.`);
}

Install with Tessl CLI

npx tessl i tessl/npm-nuxt--vite-builder

docs

client-building.md

css-processing.md

development-server.md

index.md

main-bundling.md

manifest-generation.md

plugin-system.md

server-building.md

tile.json