From 4dede5553f981dc87931de996b47f7036a883e5d Mon Sep 17 00:00:00 2001 From: Strek Date: Mon, 7 Feb 2022 19:45:31 +0530 Subject: [PATCH] docs(readme): added types (#1418) --- README.md | 276 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 219 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index d6f9e924..ff138ab7 100644 --- a/README.md +++ b/README.md @@ -70,19 +70,26 @@ If, for one reason or another, you need to extract CSS as a file (i.e. do not st ## Options -| Name | Type | Default | Description | -| :-----------------------------------: | :------------------------------------------: | :----------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **[`url`](#url)** | `{Boolean\|Object}` | `true` | Allows to enables/disables `url()`/`image-set()` functions handling | -| **[`import`](#import)** | `{Boolean\|Object}` | `true` | Allows to enables/disables `@import` at-rules handling | -| **[`modules`](#modules)** | `{Boolean\|String\|Object}` | `{auto: true}` | Allows to enables/disables or setup CSS Modules options | -| **[`sourceMap`](#sourcemap)** | `{Boolean}` | `compiler.devtool` | Enables/Disables generation of source maps | -| **[`importLoaders`](#importloaders)** | `{Number}` | `0` | Allows enables/disables or setups number of loaders applied before CSS loader for `@import`/CSS Modules and ICSS imports | -| **[`esModule`](#esmodule)** | `{Boolean}` | `true` | Use ES modules syntax | -| **[`exportType`](#exporttype)** | `{'array' \| 'string' \| 'css-style-sheet'}` | `array` | Allows exporting styles as array with modules, string or [constructable stylesheet](https://developers.google.com/web/updates/2019/02/constructable-stylesheets) (i.e. [`CSSStyleSheet`](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet)) | +- **[`url`](#url)** +- **[`import`](#import)** +- **[`modules`](#modules)** +- **[`sourceMap`](#sourcemap)** +- **[`importLoaders`](#importloaders)** +- **[`esModule`](#esmodule)** +- **[`exportType`](#exporttype)** ### `url` -Type: `Boolean|Object` +Type: + +```ts +type url = + | boolean + | { + url: (url: string, resourcePath: string) => boolean; + }; +``` + Default: `true` Allow to enable/disables handling the CSS functions `url` and `image-set`. @@ -92,7 +99,7 @@ Starting with version [4.0.0](https://github.com/webpack-contrib/css-loader/blob Examples resolutions: -``` +```js url(image.png) => require('./image.png') url('image.png') => require('./image.png') url(./image.png) => require('./image.png') @@ -103,13 +110,13 @@ image-set(url('image2x.png') 1x, url('image1x.png') 2x) => require('./image1x.pn To import assets from a `node_modules` path (include `resolve.modules`) and for `alias`, prefix it with a `~`: -``` +```js url(~module/image.png) => require('module/image.png') url('~module/image.png') => require('module/image.png') url(~aliasDirectory/image.png) => require('otherDirectory/image.png') ``` -#### `Boolean` +#### `boolean` Enable/disable `url()` resolving. @@ -131,7 +138,7 @@ module.exports = { }; ``` -#### `Object` +#### `object` Allow to filter `url()`. All filtered `url()` will not be resolved (left in the code as they were written). @@ -166,7 +173,16 @@ module.exports = { ### `import` -Type: `Boolean|Object` +Type: + + + +```ts +type import = + | boolean + | { filter: (url: string, media: string, resourcePath: string) => boolean }; +``` + Default: `true` Allows to enables/disables `@import` at-rules handling. @@ -192,7 +208,7 @@ To import styles from a `node_modules` path (include `resolve.modules`) and for @import url(~aliasDirectory/style.css) => require('otherDirectory/style.css') ``` -#### `Boolean` +#### `boolean` Enable/disable `@import` resolving. @@ -214,15 +230,16 @@ module.exports = { }; ``` -#### `Object` - -| Name | Type | Default | Description | -| :---------------------: | :----------: | :---------: | :------------------------ | -| **[`filter`](#filter)** | `{Function}` | `undefined` | Allow to filter `@import` | +#### `object` ##### `filter` -Type: `Function` +Type: + +```ts +type filter = (url: string, media: string, resourcePath: string) => boolean; +``` + Default: `undefined` Allow to filter `@import`. All filtered `@import` will not be resolved (left in the code as they were written). @@ -258,7 +275,47 @@ module.exports = { ### `modules` -Type: `Boolean|String|Object` +Type: + +```ts +type modules = + | boolean + | "local" + | "global" + | "pure" + | "icss" + | { + auto: boolean | regExp | ((resourcePath: string) => boolean); + mode: + | "local" + | "global" + | "pure" + | "icss" + | ((resourcePath) => "local" | "global" | "pure" | "icss"); + localIdentName: string; + localIdentContext: string; + localIdentHashSalt: string; + localIdentHashFunction: string; + localIdentHashDigest: string; + localIdentRegExp: string | regExp; + getLocalIdent: ( + context: LoaderContext, + localIdentName: string, + localName: string + ) => string; + namedExport: boolean; + exportGlobals: boolean; + exportLocalsConvention: + | "asIs" + | "camelCase" + | "camelCaseOnly" + | "dashes" + | "dashesOnly" + | ((name: string) => string); + exportOnlyLocals: boolean; + }; +``` + Default: `undefined` Allows to enable/disable CSS Modules or ICSS and setup configuration: @@ -448,7 +505,7 @@ We recommend use prefix `v-` for values, `s-` for selectors and `m-` for media a } ``` -#### `Boolean` +#### `boolean` Enable **CSS Modules** features. @@ -470,7 +527,7 @@ module.exports = { }; ``` -#### `String` +#### `string` Enable **CSS Modules** features and setup `mode`. @@ -493,7 +550,7 @@ module.exports = { }; ``` -#### `Object` +#### `object` Enable **CSS Modules** features and setup options for them. @@ -527,7 +584,12 @@ module.exports = { ##### `auto` -Type: `Boolean|RegExp|Function` +Type: + +```ts +type auto = boolean | regExp | ((resourcePath: string) => boolean); +``` + Default: `undefined` Allows auto enable CSS modules/ICSS based on filename when `modules` option is object. @@ -540,7 +602,7 @@ Possible values: - `RegExp` - enable CSS modules for all files matching `/RegExp/i.test(filename)` regexp. - `function` - enable CSS Modules for files based on the filename satisfying your filter function check. -###### `Boolean` +###### `boolean` Possible values: @@ -591,7 +653,7 @@ module.exports = { }; ``` -###### `Function` +###### `function` Enable css modules for files based on the filename satisfying your filter function check. @@ -617,7 +679,17 @@ module.exports = { ##### `mode` -Type: `String|Function` +Type: + +```ts +type mode = + | "local" + | "global" + | "pure" + | "icss" + | ((resourcePath) => "local" | "global" | "pure" | "icss"))` +``` + Default: `'local'` Setup `mode` option. You can omit the value when you want `local` mode. @@ -629,7 +701,7 @@ The `icss` will only compile the low level `Interoperable CSS` format for declar ICSS underpins CSS Module support, and provides a low level syntax for other tools to implement CSS-module variations of their own. -###### `String` +###### `string` Possible values - `local`, `global`, `pure`, and `icss`. @@ -653,7 +725,7 @@ module.exports = { }; ``` -###### `Function` +###### `function` Allows set different values for the `mode` option based on a filename @@ -692,7 +764,12 @@ module.exports = { ##### `localIdentName` -Type: `String` +Type: + +```ts +type localIdentName = string; +``` + Default: `'[hash:base64]'` Allows to configure the generated local ident name. @@ -747,7 +824,12 @@ module.exports = { ##### `localIdentContext` -Type: `String` +Type: + +```ts +type localIdentContex = string; +``` + Default: `compiler.context` Allows to redefine basic loader context for local ident name. @@ -774,7 +856,12 @@ module.exports = { ##### `localIdentHashSalt` -Type: `String` +Type: + +```ts +type localIdentHashSalt = string; +``` + Default: `undefined` Allows to add custom hash to generate more unique classes. @@ -802,7 +889,12 @@ module.exports = { ##### `localIdentHashFunction` -Type: `String` +Type: + +```ts +type localIdentHashFunction = string; +``` + Default: `md4` Allows to specify hash function to generate classes . @@ -830,7 +922,12 @@ module.exports = { ##### `localIdentHashDigest` -Type: `String` +Type: + +```ts +type localIdentHashDigest = string; +``` + Default: `hex` Allows to specify hash digest to generate classes. @@ -858,7 +955,12 @@ module.exports = { ##### `localIdentHashDigestLength` -Type: `Number` +Type: + +```ts +type localIdentHashDigestLength = number; +``` + Default: `20` Allows to specify hash digest length to generate classes. @@ -916,7 +1018,12 @@ module.exports = { ##### `localIdentRegExp` -Type: `String|RegExp` +Type: + +```ts +type localIdentRegExp = string | RegExp; +``` + Default: `undefined` **webpack.config.js** @@ -941,7 +1048,16 @@ module.exports = { ##### `getLocalIdent` -Type: `Function` +Type: + +```ts +type getLocalIdent = ( + context: LoaderContext, + localIdentName: string, + localName: string +) => string; +``` + Default: `undefined` Allows to specify a function to generate the classname. @@ -973,7 +1089,12 @@ module.exports = { ##### `namedExport` -Type: `Boolean` +Type: + +```ts +type namedExport = boolean; +``` + Default: `false` Enables/disables ES modules named export for locals. @@ -1029,7 +1150,12 @@ Example below in the [`examples`](#examples) section. ##### `exportGlobals` -Type: `Boolean` +Type: + +```ts +type exportsGLobals = boolean; +``` + Default: `false` Allow `css-loader` to export names from global class or id, so you can use that as local name. @@ -1056,24 +1182,35 @@ module.exports = { ##### `exportLocalsConvention` -Type: `String|Function` +Type: + +```ts +type exportLocalsConvention = + | "asIs" + | "camelCase" + | "camelCaseOnly" + | "dashes" + | "dashesOnly" + | ((name: string) => string); +``` + Default: based on the `modules.namedExport` option value, if `true` - `camelCaseOnly`, otherwise `asIs` Style of exported class names. -###### `String` +###### `string` By default, the exported JSON keys mirror the class names (i.e `asIs` value). > ⚠ Only `camelCaseOnly` value allowed if you set the `namedExport` value to `true`. -| Name | Type | Description | -| :-------------------: | :--------: | :----------------------------------------------------------------------------------------------- | -| **`'asIs'`** | `{String}` | Class names will be exported as is. | -| **`'camelCase'`** | `{String}` | Class names will be camelized, the original class name will not to be removed from the locals | -| **`'camelCaseOnly'`** | `{String}` | Class names will be camelized, the original class name will be removed from the locals | -| **`'dashes'`** | `{String}` | Only dashes in class names will be camelized | -| **`'dashesOnly'`** | `{String}` | Dashes in class names will be camelized, the original class name will be removed from the locals | +| Name | Type | Description | +| :-------------------: | :------: | :----------------------------------------------------------------------------------------------- | +| **`'asIs'`** | `string` | Class names will be exported as is. | +| **`'camelCase'`** | `string` | Class names will be camelized, the original class name will not to be removed from the locals | +| **`'camelCaseOnly'`** | `string` | Class names will be camelized, the original class name will be removed from the locals | +| **`'dashes'`** | `string` | Only dashes in class names will be camelized | +| **`'dashesOnly'`** | `string` | Dashes in class names will be camelized, the original class name will be removed from the locals | **file.css** @@ -1108,7 +1245,7 @@ module.exports = { }; ``` -###### `Function` +###### `function` **webpack.config.js** @@ -1162,7 +1299,12 @@ module.exports = { ##### `exportOnlyLocals` -Type: `Boolean` +Type: + +```ts +type exportOnlyLocals = boolean; +``` + Default: `false` Export only locals. @@ -1193,7 +1335,12 @@ module.exports = { ### `importLoaders` -Type: `Number` +Type: + +```ts +type importLoaders = number; +``` + Default: `0` Allows to enables/disables or setups number of loaders applied before CSS loader for `@import` at-rules, CSS modules and ICSS imports, i.e. `@import`/`composes`/`@value value from './values.css'`/etc. @@ -1232,7 +1379,12 @@ This may change in the future when the module system (i. e. webpack) supports lo ### `sourceMap` -Type: `Boolean` +Type: + +```ts +type sourceMap = boolean; +``` + Default: depends on the `compiler.devtool` value By default generation of source maps depends on the [`devtool`](https://webpack.js.org/configuration/devtool/) option. All values enable source map generation except `eval` and `false` value. @@ -1257,7 +1409,12 @@ module.exports = { ### `esModule` -Type: `Boolean` +Type: + +```ts +type esModule = boolean; +``` + Default: `true` By default, `css-loader` generates JS modules that use the ES modules syntax. @@ -1285,7 +1442,12 @@ module.exports = { ### `exportType` -Type: `'array' | 'string' | 'css-style-sheet'` +Type: + +```ts +type exportType = "array" | "string" | "css-style-sheet"; +``` + Default: `'array'` Allows exporting styles as array with modules, string or [constructable stylesheet](https://developers.google.com/web/updates/2019/02/constructable-stylesheets) (i.e. [`CSSStyleSheet`](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet)).