@applaud/postcss-loader
v1.0.0
Published
PostCSS loader for webpack
Downloads
27
Maintainers
Readme
npm i -D @applaud/postcss-loader
Configuration
postcss.config.js
module.exports = {
parser: 'sugarss',
plugins: {
'postcss-import': {},
'postcss-preset-env': {},
'cssnano': {}
}
}
You can read more about common PostCSS Config here.
Config Cascade
You can use different postcss.config.js
files in different directories.
Config lookup starts from path.dirname(file)
and walks the file tree upwards until a config file is found.
|– components
| |– component
| | |– index.js
| | |– index.png
| | |– style.css (1)
| | |– postcss.config.js (1)
| |– component
| | |– index.js
| | |– image.png
| | |– style.css (2)
|
|– postcss.config.js (1 && 2 (recommended))
|– webpack.config.js
|
|– package.json
After setting up your postcss.config.js
, add @applaud/postcss-loader
to your webpack.config.js
. You can use it standalone or in conjunction with css-loader
(recommended). Use it after css-loader
and style-loader
, but before other preprocessor loaders like e.g sass|less|stylus-loader
, if you use any.
webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: [ 'style-loader', '@applaud/postcss-loader' ]
}
]
}
}
⚠️ When
@applaud/postcss-loader
is used standalone (withoutcss-loader
) don't use@import
in your CSS, since this can lead to quite bloated bundles
webpack.config.js
(recommended)
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: [
'style-loader',
{ loader: 'css-loader', options: { importLoaders: 1 } },
'@applaud/postcss-loader'
]
}
]
}
}
|Name|Type|Default|Description|
|:--:|:--:|:-----:|:----------|
|exec
|{Boolean}
|undefined
|Enable PostCSS Parser support in CSS-in-JS
|
|parser
|{String\|Object}
|undefined
|Set PostCSS Parser|
|syntax
|{String\|Object}
|undefined
|Set PostCSS Syntax|
|stringifier
|{String\|Object}
|undefined
|Set PostCSS Stringifier|
|config
|{Object}
|undefined
|Set postcss.config.js
config path && ctx
|
|plugins
|{Array\|Function}
|[]
|Set PostCSS Plugins|
|sourceMap
|{String\|Boolean}
|false
|Enable Source Maps|
Exec
If you use JS styles without the postcss-js
parser, add the exec
option.
webpack.config.js
{
test: /\.style.js$/,
use: [
'style-loader',
{ loader: 'css-loader', options: { importLoaders: 1 } },
{ loader: '@applaud/postcss-loader', options: { parser: 'sugarss', exec: true } }
]
}
Config
|Name|Type|Default|Description|
|:--:|:--:|:-----:|:----------|
|path
|{String}
|undefined
|PostCSS Config Directory|
|context
|{Object}
|undefined
|PostCSS Config Context|
Path
You can manually specify the path to search for your config (postcss.config.js
) with the config.path
option. This is needed if you store your config in a separate e.g ./config || ./.config
folder.
⚠️ Otherwise it is unnecessary to set this option and is not recommended
⚠️ Note that you can't use a filename other than the supported config formats (e.g
.postcssrc.js
,postcss.config.js
), this option only allows you to manually specify the directory where config lookup should start from
webpack.config.js
{
loader: '@applaud/postcss-loader',
options: {
config: {
path: 'path/to/.config/' ✅
path: 'path/to/.config/css.config.js' ❌
}
}
}
Context (ctx)
|Name|Type|Default|Description|
|:--:|:--:|:-----:|:----------|
|env
|{String}
|'development'
|process.env.NODE_ENV
|
|file
|{Object}
|loader.resourcePath
|extname
, dirname
, basename
|
|options
|{Object}
|{}
|Options|
@applaud/postcss-loader
exposes context ctx
to the config file, making your postcss.config.js
dynamic, so can use it to do some real magic ✨
postcss.config.js
module.exports = ({ file, options, env }) => ({
parser: file.extname === '.sss' ? 'sugarss' : false,
plugins: {
'postcss-import': { root: file.dirname },
'postcss-preset-env': options['postcss-preset-env'] ? options['postcss-preset-env'] : false,
'cssnano': env === 'production' ? options.cssnano : false
}
})
webpack.config.js
{
loader: '@applaud/postcss-loader',
options: {
config: {
ctx: {
'postcss-preset-env': {...options},
cssnano: {...options},
}
}
}
}
Plugins
webpack.config.js
{
loader: '@applaud/postcss-loader',
options: {
ident: 'postcss',
plugins: (loader) => [
require('postcss-import')({ root: loader.resourcePath }),
require('postcss-preset-env')(),
require('cssnano')()
]
}
}
⚠️ webpack requires an identifier (
ident
) inoptions
when{Function}/require
is used (Complex Options). Theident
can be freely named as long as it is unique. It's recommended to name it (ident: 'postcss'
)
Syntaxes
|Name|Type|Default|Description|
|:--:|:--:|:-----:|:----------|
|parser
|{String\|Function}
|undefined
|Custom PostCSS Parser|
|syntax
|{String\|Function}
|undefined
|Custom PostCSS Syntax|
|stringifier
|{String\|Function}
|undefined
|Custom PostCSS Stringifier|
Parser
webpack.config.js
{
test: /\.sss$/,
use: [
...,
{ loader: '@applaud/postcss-loader', options: { parser: 'sugarss' } }
]
}
Syntax
webpack.config.js
{
test: /\.css$/,
use: [
...,
{ loader: '@applaud/postcss-loader', options: { syntax: 'sugarss' } }
]
}
Stringifier
webpack.config.js
{
test: /\.css$/,
use: [
...,
{ loader: '@applaud/postcss-loader', options: { stringifier: 'midas' } }
]
}
SourceMap
Enables source map support, @applaud/postcss-loader
will use the previous source map given by other loaders and update it accordingly, if no previous loader is applied before @applaud/postcss-loader
, the loader will generate a source map for you.
webpack.config.js
{
test: /\.css/,
use: [
{ loader: 'style-loader', options: { sourceMap: true } },
{ loader: 'css-loader', options: { sourceMap: true } },
{ loader: '@applaud/postcss-loader', options: { sourceMap: true } },
{ loader: 'sass-loader', options: { sourceMap: true } }
]
}
'inline'
You can set the sourceMap: 'inline'
option to inline the source map
within the CSS directly as an annotation comment.
webpack.config.js
{
loader: '@applaud/postcss-loader',
options: {
sourceMap: 'inline'
}
}
.class { color: red; }
/*# sourceMappingURL=data:application/json;base64, ... */
Stylelint
webpack.config.js
{
test: /\.css$/,
use: [
'style-loader',
'css-loader',
{
loader: '@applaud/postcss-loader',
options: {
ident: 'postcss',
plugins: [
require('postcss-import')(),
require('stylelint')(),
...,
]
}
}
]
}
Autoprefixing
webpack.config.js
{
test: /\.css$/,
use: [
'style-loader',
'css-loader',
{
loader: '@applaud/postcss-loader',
options: {
ident: 'postcss',
plugins: [
require('autoprefixer')({...options}),
...,
]
}
}
]
}
:warning:
postcss-preset-env
includesautoprefixer
, so adding it separately is not necessary if you already use the preset.
CSS Modules
This loader cannot be used with CSS Modules out of the box due
to the way css-loader
processes file imports. To make them work properly,
either add the css-loader’s importLoaders
option.
webpack.config.js
{
test: /\.css$/,
use: [
'style-loader',
{ loader: 'css-loader', options: { modules: true, importLoaders: 1 } },
'@applaud/postcss-loader'
]
}
or use postcss-modules instead of css-loader
.
CSS-in-JS
If you want to process styles written in JavaScript, use the postcss-js parser.
webpack.config.js
{
test: /\.style.js$/,
use: [
'style-loader',
{ loader: 'css-loader', options: { importLoaders: 2 } },
{ loader: '@applaud/postcss-loader', options: { parser: 'postcss-js' } },
'babel-loader'
]
}
As result you will be able to write styles in the following way
import colors from './styles/colors'
export default {
'.menu': {
color: colors.main,
height: 25,
'&_link': {
color: 'white'
}
}
}
:warning: If you are using Babel you need to do the following in order for the setup to work
- Add babel-plugin-add-module-exports to your configuration
- You need to have only one default export per style module
Extract CSS
webpack.config.js
const devMode = process.env.NODE_ENV !== 'production'
const MiniCssExtractPlugin = require('mini-css-extract-plugin')
module.exports = {
module: {
rules: [
{
test: /\.css$/,
use: [
devMode ? 'style-loader' : MiniCssExtractPlugin.loader,
'css-loader',
'@applaud/postcss-loader'
]
}
]
},
plugins: [
new MiniCssExtractPlugin({
filename: devMode ? '[name].css' : '[name].[hash].css'
})
]
}