Wondering what’s next for npm?Check out our public roadmap! »

    postcss-load-config
    TypeScript icon, indicating that this package has built-in type declarations

    3.1.0 • Public • Published

    npm node deps test coverage code style chat

    Load Config

    Install

    npm i -D postcss-load-config

    Usage

    npm i -S|-D postcss-plugin

    Install all required postcss plugins and save them to your package.json dependencies/devDependencies

    Then create a postcss config file by choosing one of the following formats

    package.json

    Create a postcss section in your project's package.json

    Project (Root)
      |– client
      |– public
      |
      |- package.json
    
    {
      "postcss": {
        "parser": "sugarss",
        "map": false,
        "plugins": {
          "postcss-plugin": {}
        }
      }
    }

    .postcssrc

    Create a .postcssrc file in JSON or YAML format

    ℹ️ It's recommended to use an extension (e.g .postcssrc.json or .postcssrc.yml) instead of .postcssrc

    Project (Root)
      |– client
      |– public
      |
      |- (.postcssrc|.postcssrc.json|.postcssrc.yml)
      |- package.json
    

    .postcssrc.json

    {
      "parser": "sugarss",
      "map": false,
      "plugins": {
        "postcss-plugin": {}
      }
    }

    .postcssrc.yml

    parser: sugarss
    map: false
    plugins:
      postcss-plugin: {}

    .postcssrc.js or postcss.config.js

    You may need some logic within your config. In this case create JS file named .postcssrc.js or postcss.config.js

    Project (Root)
      |– client
      |– public
      |
      |- (.postcssrc.js|postcss.config.js)
      |- package.json
    

    You can export the config as an {Object}

    .postcssrc.js

    module.exports = {
      parser: 'sugarss',
      map: false,
      plugins: {
        'postcss-plugin': {}
      }
    }

    Or export a {Function} that returns the config (more about the ctx param below)

    .postcssrc.js

    module.exports = (ctx) => ({
      parser: ctx.parser ? 'sugarss' : false,
      map: ctx.env === 'development' ? ctx.map : false,
      plugins: {
        'postcss-plugin': ctx.options.plugin
      }
    })

    Plugins can be loaded either using an {Object} or an {Array}

    {Object}

    .postcssrc.js

    module.exports = ({ env }) => ({
      ...options,
      plugins: {
        'postcss-plugin': env === 'production' ? {} : false
      }
    })

    {Array}

    .postcssrc.js

    module.exports = ({ env }) => ({
      ...options,
      plugins: [
        env === 'production' ? require('postcss-plugin')() : false
      ]
    })

    ⚠️ When using an {Array}, make sure to require() each plugin

    Options

    Name Type Default Description
    to {String} undefined Destination File Path
    map {String|Object} false Enable/Disable Source Maps
    from {String} undefined Source File Path
    parser {String|Function} false Custom PostCSS Parser
    syntax {String|Function} false Custom PostCSS Syntax
    stringifier {String|Function} false Custom PostCSS Stringifier

    parser

    .postcssrc.js

    module.exports = {
      parser: 'sugarss'
    }

    syntax

    .postcssrc.js

    module.exports = {
      syntax: 'postcss-scss'
    }

    stringifier

    .postcssrc.js

    module.exports = {
      stringifier: 'midas'
    }

    map

    .postcssrc.js

    module.exports = {
      map: 'inline'
    }

    ⚠️ In most cases options.from && options.to are set by the third-party which integrates this package (CLI, gulp, webpack). It's unlikely one needs to set/use options.from && options.to within a config file. Unless you're a third-party plugin author using this module and its Node API directly dont't set options.from && options.to yourself

    to

    module.exports = {
      to: 'path/to/dest.css'
    }

    from

    module.exports = {
      from: 'path/to/src.css'
    }

    Plugins

    {} || null

    The plugin will be loaded with defaults

    'postcss-plugin': {} || null

    .postcssrc.js

    module.exports = {
      plugins: {
        'postcss-plugin': {} || null
      }
    }

    ⚠️ {} must be an empty {Object} literal

    {Object}

    The plugin will be loaded with given options

    'postcss-plugin': { option: '', option: '' }

    .postcssrc.js

    module.exports = {
      plugins: {
        'postcss-plugin': { option: '', option: '' }
      }
    }

    false

    The plugin will not be loaded

    'postcss-plugin': false

    .postcssrc.js

    module.exports = {
      plugins: {
        'postcss-plugin': false
      }
    }

    Ordering

    Plugin execution order is determined by declaration in the plugins section (top-down)

    {
      plugins: {
        'postcss-plugin': {}, // [0]
        'postcss-plugin': {}, // [1]
        'postcss-plugin': {}  // [2]
      }
    }

    Context

    When using a {Function} (postcss.config.js or .postcssrc.js), it's possible to pass context to postcss-load-config, which will be evaluated while loading your config. By default ctx.env (process.env.NODE_ENV) and ctx.cwd (process.cwd()) are available on the ctx {Object}

    ℹ️ Most third-party integrations add additional properties to the ctx (e.g postcss-loader). Check the specific module's README for more information about what is available on the respective ctx

    Examples

    postcss.config.js

    module.exports = (ctx) => ({
      parser: ctx.parser ? 'sugarss' : false,
      map: ctx.env === 'development' ? ctx.map : false,
      plugins: {
        'postcss-import': {},
        'postcss-nested': {},
        cssnano: ctx.env === 'production' ? {} : false
      }
    })
    "scripts": {
      "build": "NODE_ENV=production node postcss",
      "start": "NODE_ENV=development node postcss"
    }

    Async

    const { readFileSync } = require('fs')
    
    const postcss = require('postcss')
    const postcssrc = require('postcss-load-config')
    
    const css = readFileSync('index.sss', 'utf8')
    
    const ctx = { parser: true, map: 'inline' }
    
    postcssrc(ctx).then(({ plugins, options }) => {
      postcss(plugins)
        .process(css, options)
        .then((result) => console.log(result.css))
    })

    Sync

    const { readFileSync } = require('fs')
    
    const postcss = require('postcss')
    const postcssrc = require('postcss-load-config')
    
    const css = readFileSync('index.sss', 'utf8')
    
    const ctx = { parser: true, map: 'inline' }
    
    const { plugins, options } = postcssrc.sync(ctx)
    "scripts": {
      "build": "NODE_ENV=production gulp",
      "start": "NODE_ENV=development gulp"
    }
    const { task, src, dest, series, watch } = require('gulp')
    
    const postcss = require('gulp-postcssrc')
    
    const css = () => {
      src('src/*.css')
        .pipe(postcss())
        .pipe(dest('dest'))
    })
    
    task('watch', () => {
      watch(['src/*.css', 'postcss.config.js'], css)
    })
    
    task('default', series(css, 'watch'))
    "scripts": {
      "build": "NODE_ENV=production webpack",
      "start": "NODE_ENV=development webpack-dev-server"
    }

    webpack.config.js

    module.exports = (env) => ({
      module: {
        rules: [
          {
            test: /\.css$/,
            use: [
              'style-loader',
              'css-loader',
              'postcss-loader'
            ]
          }
        ]
      }
    })

    Maintainers


    Michael Ciniawsky

    Mateusz Derks

    Contributors


    Ryan Dunckel

    Patrick Gilday

    Dalton Santos

    Security Contact

    To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.

    Install

    npm i postcss-load-config

    DownloadsWeekly Downloads

    8,280,521

    Version

    3.1.0

    License

    MIT

    Unpacked Size

    22 kB

    Total Files

    7

    Last publish

    Collaborators

    • avatar
    • avatar