CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-gatsby-plugin-less

Gatsby plugin to add support for using Less CSS preprocessor with webpack configuration

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

gatsby-plugin-less

gatsby-plugin-less provides seamless integration of Less CSS preprocessor into Gatsby projects. It automatically configures webpack to handle .less files through a processing pipeline that includes less-loader for Less compilation, css-loader for CSS modules support, postcss-loader for autoprefixing and optimization, and mini-css-extract-plugin for CSS extraction.

Package Information

  • Package Name: gatsby-plugin-less
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install gatsby-plugin-less less

Core Imports

This plugin is configured through Gatsby's plugin system, not imported directly:

// in gatsby-config.js
module.exports = {
  plugins: [`gatsby-plugin-less`]
}

With configuration options:

// in gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-less`,
      options: {
        // Plugin options go here
      }
    }
  ]
}

Basic Usage

Simple Setup

Add the plugin to your gatsby-config.js and start using .less files:

// gatsby-config.js
module.exports = {
  plugins: [`gatsby-plugin-less`]
}
// src/styles/main.less
@primary-color: #1890ff;

.header {
  color: @primary-color;
  font-size: 24px;
  
  &:hover {
    color: darken(@primary-color, 10%);
  }
}
// src/components/Header.js
import '../styles/main.less';

export default function Header() {
  return <h1 className="header">Welcome</h1>;
}

With CSS Modules

CSS modules work automatically with .module.less files:

// src/components/Button.module.less
@button-height: 40px;

.button {
  height: @button-height;
  padding: 0 16px;
  border: none;
  border-radius: 4px;
  
  &.primary {
    background: #1890ff;
    color: white;
  }
}
// src/components/Button.js
import { button, primary } from './Button.module.less';

export default function Button({ variant, children }) {
  return (
    <button className={variant === 'primary' ? `${button} ${primary}` : button}>
      {children}
    </button>
  );
}

Capabilities

Plugin Configuration

Configures webpack to process Less files in Gatsby applications.

// Plugin configuration in gatsby-config.js
{
  resolve: `gatsby-plugin-less`,
  options: {
    lessOptions?: LessOptions;
    loaderOptions?: LessLoaderOptions;
    cssLoaderOptions?: CssLoaderOptions;  
    postCssPlugins?: PostCSSPlugin[];
  }
}

Less Compiler Options

Configure the Less compiler behavior.

/**
 * Less compiler configuration options
 * @typedef {Object} LessOptions
 * @property {boolean} [strictMath] - Enable strict math mode for calculations
 * @property {LessPlugin[]} [plugins] - Array of Less plugins
 * @property {Object.<string, string>} [modifyVars] - Modify Less variables at compile time
 * @property {string[]} [paths] - Paths to search for @import directives
 * @property {boolean} [relativeUrls] - Enable relative URLs
 * @property {boolean} [compress] - Compress output CSS
 * @property {boolean|SourceMapOptions} [sourceMap] - Generate source maps
 */

Usage:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-less`,
      options: {
        lessOptions: {
          strictMath: true,
          modifyVars: {
            'primary-color': '#ff6b35',
            'border-radius-base': '2px'
          },
          plugins: [
            new (require('less-plugin-clean-css'))({ advanced: true })
          ]
        }
      }
    }
  ]
}

// Alternative: Load variables from an external file
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-less`,
      options: {
        lessOptions: {
          modifyVars: require('./src/theme.js')
        }
      }
    }
  ]
}

Where theme.js exports a variable object:

// src/theme.js
module.exports = {
  'primary-color': '#1890ff',
  'text-color': '#333'
}

Less Loader Options

Configure less-loader specific behavior.

/**
 * Less loader configuration options
 * @typedef {Object} LessLoaderOptions
 * @property {string} [appendData] - Append data to every Less file
 * @property {string} [prependData] - Prepend data to every Less file
 * @property {string|Function} [additionalData] - Additional data to pass to Less compiler
 * @property {Object} [implementation] - Custom Less implementation to use instead of default
 * @property {boolean} [sourceMap] - Source map configuration
 */

Usage:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-less`,
      options: {
        loaderOptions: {
          appendData: `@env: ${process.env.NODE_ENV};`
        }
      }
    }
  ]
}

CSS Loader Options

Configure css-loader behavior for CSS processing.

/**
 * CSS loader configuration options
 * @typedef {Object} CssLoaderOptions
 * @property {boolean|CssModulesOptions} [modules] - Enable/disable CSS modules
 * @property {boolean} [camelCase] - Enable/disable camelCase transformation
 * @property {boolean} [esModule] - Enable/disable ES modules syntax for exported names
 * @property {number} [importLoaders] - Number of loaders applied before css-loader
 * @property {boolean} [sourceMap] - Enable/disable source maps
 * @property {boolean} [import] - Enable/disable CSS imports resolution
 * @property {boolean} [url] - Enable/disable CSS url() resolution
 */

/**
 * CSS modules configuration options
 * @typedef {Object} CssModulesOptions
 * @property {boolean} [namedExport] - Enable named exports for CSS modules
 * @property {string} [localIdentName] - CSS class naming pattern
 * @property {boolean} [exportGlobals] - Export globals alongside CSS modules
 */

Usage:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-less`,
      options: {
        cssLoaderOptions: {
          camelCase: false,
          esModule: false,
          modules: {
            namedExport: false,
            localIdentName: '[name]__[local]--[hash:base64:5]'
          }
        }
      }
    }
  ]
}

PostCSS Plugin Configuration

Add PostCSS plugins for additional CSS processing.

/**
 * PostCSS plugin configuration
 * @typedef {Object} PostCSSPlugin
 * @property {string|Function} plugin - Plugin name or instance
 * @property {*} [options] - Plugin options
 */

Usage:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-less`,
      options: {
        postCssPlugins: [
          require('autoprefixer')({ grid: true }),
          require('cssnano')({ preset: 'default' })
        ]
      }
    }
  ]
}

File Processing Patterns

Regular Less Files

Files matching *.less pattern are processed with CSS modules disabled by default.

  • Pattern: /\.less$/
  • Loader Chain: mini-css-extract-plugin → css-loader → postcss-loader → less-loader
  • CSS Modules: Disabled
  • Output: Extracted CSS files

CSS Module Less Files

Files matching *.module.less pattern are processed with CSS modules enabled.

  • Pattern: /\.module\.less$/
  • Loader Chain: mini-css-extract-plugin → css-loader (with modules) → postcss-loader → less-loader
  • CSS Modules: Enabled with named exports (default: true, can be configured via cssLoaderOptions.modules.namedExport)
  • Output: CSS modules with scoped class names

Server-Side Rendering

During SSR stages (develop-html, build-html), CSS processing is bypassed using null loaders to prevent issues during HTML generation.

// SSR behavior (automatic)
const isSSR = [`develop-html`, `build-html`].includes(stage);
// Uses null loader instead of CSS processing chain during SSR

Types

/**
 * Gatsby plugin options for gatsby-plugin-less
 * @typedef {Object} GatsbyPluginLessOptions
 * @property {Object} [lessOptions] - Options passed to the Less compiler
 * @property {Object} [loaderOptions] - Options passed to less-loader  
 * @property {Object} [cssLoaderOptions] - Options passed to css-loader
 * @property {Array} [postCssPlugins] - Array of PostCSS plugins to apply
 */

/**
 * Less plugin interface
 * @typedef {Object} LessPlugin
 * @property {Function} install - Plugin installation method (less: any, pluginManager: any) => void
 * @property {number[]} [minVersion] - Plugin minimum Less version requirement
 */

/**
 * Source map configuration options
 * @typedef {Object} SourceMapOptions
 * @property {boolean} [sourceMapContents] - Include source content in source map
 * @property {string} [sourceMapFilename] - Include filename in source map
 * @property {string} [sourceMapBasepath] - Base path for source map URLs
 * @property {string} [sourceMapRootpath] - Root path for source map
 * @property {string} [sourceMapURL] - URL for source map
 */

docs

index.md

tile.json