Neutrino Style Loader Middleware¶
@neutrinojs/style-loader
is Neutrino middleware for loading and importing stylesheets from modules.
Features¶
- Zero upfront configuration necessary to import stylesheets into modules
- Automatic stylesheet extraction; importing stylesheets into modules creates bundled external stylesheets
- Pre-configured to support CSS Modules via
*.module.css
file extensions - CSS Hot Module Replacement support
- Very extensible to customize as needed
Requirements¶
- Node.js v8.3+
- Yarn v1.2.1+, or npm v5.4+
- Neutrino v8
Installation¶
@neutrinojs/style-loader
can be installed via the Yarn or npm clients.
Yarn¶
❯ yarn add @neutrinojs/style-loader
npm¶
❯ npm install --save @neutrinojs/style-loader
Usage¶
@neutrinojs/style-loader
can be consumed from the Neutrino API, middleware, or presets. Require this package
and plug it into Neutrino:
// Using function middleware format const styles = require('@neutrinojs/style-loader'); // Use with default options neutrino.use(styles); // Usage showing default options neutrino.use(styles, { style: {}, css: {}, loaders: [], test: /\.css$/, ruleId: 'style', styleUseId: 'style', cssUseId: 'css', modules: true, modulesSuffix: '-modules', modulesTest: /\.module.css$/, extractId: 'extract', extract: { plugin: {}, loader: { filename: process.env.NODE_ENV === 'production' ? '[name].[contenthash:8].css' : '[name].css' } } });
// Using object or array middleware format // Use with default options module.exports = { use: ['@neutrinojs/style-loader'] }; // Usage showing default options module.exports = { use: [ ['@neutrinojs/style-loader', { style: {}, css: {}, loaders: [], test: /\.css$/, ruleId: 'style', styleUseId: 'style', cssUseId: 'css', modules: true, modulesSuffix: '-modules', modulesTest: /\.module.css$/, extractId: 'extract', extract: { plugin: {}, loader: { filename: process.env.NODE_ENV === 'production' ? '[name].[contenthash:8].css' : '[name].css' } } }] ] };
style
: Set options for the style-loader used when loading CSS files.css
: Set options for the css-loader used when loading CSS files.loaders
: Provide an array of custom loaders used when loading stylesheetstest
: File extensions which support stylesheetsruleId
: The ID of the webpack-chain rule used to identify the stylesheet loadersstyleUseId
: The ID of the webpack-chainuse
used to identify the style-loadercssUseId
: The ID of the webpack-chainuse
used to identify the css-loadermodules
: Enable usage of CSS modules via*.module.css
files. Set tofalse
to disable and skip defining these rules.modulesSuffix
: A suffix added toruleId
,styleUseId
,cssUseId
,hotUseId
, andextractId
to derive names for modules-related rules. For example, the default-modules
suffix will generate a rule ID for the CSS modules rules ofstyle-modules
, while the normal rule remains asstyle
.modulesTest
: File extensions which support CSS Modules stylesheetsextractId
: The ID of the webpack-chain plugin used to identify theExtractTextPlugin
extract
: Options relating to theExtractTextPlugin
instance. Overrideextract.plugin
to override plugin options. Overrideextract.loader
to override the loader options. Set tofalse
to disable stylesheet extraction.
Custom Loaders¶
You may wish to perform custom loading on your stylesheets by using SASS, LESS, postcss, and more. You can do this
by providing an array of custom loaders to the loaders
options to this middleware. Each item in the loaders
array
corresponds to a webpack loader to use, and can be defined as an object or as a string.
Using an object to define loaders is preferred since it allows options to be overridable in the future, and by other consuming middleware. Each loader object can specify 3 properties:
loader
: A string referencing the path to the loader to use, e.g.sass-loader
orrequire.resolve('less-loader')
.options
: An object specifying any options needed by the loader.useId
: A string identified for the loader, used to reference the loader in the future for overrides or customization by other middleware.
Using a string to define loaders will cause @neutrinojs/style-loader
to still generate a loader object. The string
will be used as the loader
property, options
will be left blank, and the useId
will be derived from
cssUseId
option above plus the index of this loader within the loaders
array.
Important: The useId
for string-defined loaders will start at 2
, since all loaders are preceded by the included
style-loader
and css-loader
.
module.exports = { use: ['@neutrinojs/style-loader', { // Override the default file extension of `.css` if needed test: /\.(css|sass|scss)$/, moduleTest: /\.module\.(css|sass|scss)$/, loaders: [ // Define loaders as objects { loader: 'sass-loader', useId: 'sass', options: { includePaths: ['absolute/path/a', 'absolute/path/b'] } }, { loader: 'postcss-loader', options: { plugins: [require('autoprefixer')] } } ] }] }
module.exports = { use: ['@neutrinojs/style-loader', { loaders: [ // Define loaders as strings // This will cause this middleware to generate a // loader with a useId of `css-2`. 'sass-loader' // Adding any other loaders will increment the useId // to `css-3`, `css-4`, etc. ] }] }
Due to the inferred loader names, we highly recommend you stick to using objects to define loaders.
Loader Configuration¶
You can configure loaders directly by passing options
.
For PostCSS, if you want to use an external config file,
you need to pass options.config
:
// .neutrinorc.js module.exports = { use: ['@neutrinojs/style-loader', { loaders: [ { loader: 'postcss-loader', useId: 'postcss', options: { config: { // Where to look for config (postcss.config.js) // https://github.com/postcss/postcss-loader#path // See "Loader Configuration" below path: neutrino.options.root } } } ] }] }
// .postcssrc.js // Example: load tailwindcss plugin module.exports = { plugins: { tailwindcss: {}, } };
Customization¶
@neutrinojs/style-loader
creates some conventions to make overriding the configuration easier once you are
ready to make changes.
Rules¶
The following is a list of default rules and their identifiers which can be overridden:
Name | Description | Environments and Commands |
---|---|---|
style |
Allows importing CSS stylesheets from modules. By default contains two loaders named extract and css which use MiniCssExtractPlugin.loader and css-loader , respectively. If options.extract is false , then the extract loader is replaced by style , which uses style-loader . |
all |
style-modules |
Allows importing CSS Modules styles from modules. By default contains two loaders named extract and css which use MiniCssExtractPlugin.loader and css-loader , respectively. If options.extract is false , then the extract loader is replaced by style , which uses style-loader . |
all |
Plugins¶
The following is a default list of plugins and their identifiers which can be overridden:
Note: Some plugins may be only available in certain environments. To override them, they should be modified conditionally.
Name | Description | Environments and Commands |
---|---|---|
extract |
Extracts CSS from JS bundle into a separate stylesheet file. | all |
Contributing¶
This middleware is part of the neutrino-dev repository, a monorepo containing all resources for developing Neutrino and its core presets and middleware. Follow the contributing guide for details.