From b1e2c8fd5cb5dfa46bc440a12eafaf56cd844b1c Mon Sep 17 00:00:00 2001 From: Philipp Tanlak Date: Mon, 24 Nov 2025 20:54:57 +0100 Subject: Docs --- node_modules/postcss-load-config/LICENSE | 20 + node_modules/postcss-load-config/README.md | 491 ++++++++++++++++++++++++ node_modules/postcss-load-config/package.json | 48 +++ node_modules/postcss-load-config/src/index.d.ts | 65 ++++ node_modules/postcss-load-config/src/index.js | 179 +++++++++ node_modules/postcss-load-config/src/options.js | 47 +++ node_modules/postcss-load-config/src/plugins.js | 85 ++++ node_modules/postcss-load-config/src/req.js | 10 + 8 files changed, 945 insertions(+) create mode 100644 node_modules/postcss-load-config/LICENSE create mode 100644 node_modules/postcss-load-config/README.md create mode 100644 node_modules/postcss-load-config/package.json create mode 100644 node_modules/postcss-load-config/src/index.d.ts create mode 100644 node_modules/postcss-load-config/src/index.js create mode 100644 node_modules/postcss-load-config/src/options.js create mode 100644 node_modules/postcss-load-config/src/plugins.js create mode 100644 node_modules/postcss-load-config/src/req.js (limited to 'node_modules/postcss-load-config') diff --git a/node_modules/postcss-load-config/LICENSE b/node_modules/postcss-load-config/LICENSE new file mode 100644 index 0000000..458e8a3 --- /dev/null +++ b/node_modules/postcss-load-config/LICENSE @@ -0,0 +1,20 @@ +The MIT License (MIT) + +Copyright Michael Ciniawsky + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS +FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR +COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER +IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/node_modules/postcss-load-config/README.md b/node_modules/postcss-load-config/README.md new file mode 100644 index 0000000..c1700f4 --- /dev/null +++ b/node_modules/postcss-load-config/README.md @@ -0,0 +1,491 @@ +[![npm][npm]][npm-url] +[![node][node]][node-url] +[![deps][deps]][deps-url] +[![test][test]][test-url] +[![coverage][cover]][cover-url] +[![code style][style]][style-url] +[![chat][chat]][chat-url] + +
+ + + + + +

Load Config

+
+ +

Install

+ +```bash +npm i -D postcss-load-config +``` + +

Usage

+ +```bash +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 +``` + +```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`** +```json +{ + "parser": "sugarss", + "map": false, + "plugins": { + "postcss-plugin": {} + } +} +``` + +**`.postcssrc.yml`** +```yaml +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` +- `.postcssrc.mjs` +- `.postcssrc.cjs` +- `.postcssrc.ts` +- `postcss.config.js` +- `postcss.config.mjs` +- `postcss.config.cjs` +- `postcss.config.ts` + +``` +Project (Root) + |– client + |– public + |- (.postcssrc|postcss.config).(js|mjs|cjs|ts) + |- package.json +``` + +You can export the config as an `{Object}` + +**.postcssrc.js** +```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** +```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** +```js +module.exports = ({ env }) => ({ + ...options, + plugins: { + 'postcss-plugin': env === 'production' ? {} : false + } +}) +``` + +> ℹ️ When using an `{Object}`, the key can be a Node.js module name, a path to a JavaScript file that is relative to the directory of the PostCSS config file, or an absolute path to a JavaScript file. + +#### `{Array}` + +**.postcssrc.js** +```js +module.exports = ({ env }) => ({ + ...options, + plugins: [ + env === 'production' ? require('postcss-plugin')() : false + ] +}) +``` +> :warning: When using an `{Array}`, make sure to `require()` each plugin + +

Options

+ +|Name|Type|Default|Description| +|:--:|:--:|:-----:|:----------| +|[**`to`**](#to)|`{String}`|`undefined`|Destination File Path| +|[**`map`**](#map)|`{String\|Object}`|`false`|Enable/Disable Source Maps| +|[**`from`**](#from)|`{String}`|`undefined`|Source File Path| +|[**`parser`**](#parser)|`{String\|Function}`|`false`|Custom PostCSS Parser| +|[**`syntax`**](#syntax)|`{String\|Function}`|`false`|Custom PostCSS Syntax| +|[**`stringifier`**](#stringifier)|`{String\|Function}`|`false`|Custom PostCSS Stringifier| + +### `parser` + +**.postcssrc.js** +```js +module.exports = { + parser: 'sugarss' +} +``` + +### `syntax` + +**.postcssrc.js** +```js +module.exports = { + syntax: 'postcss-scss' +} +``` + +### `stringifier` + +**.postcssrc.js** +```js +module.exports = { + stringifier: 'midas' +} +``` + +### [**`map`**](https://github.com/postcss/postcss/blob/master/docs/source-maps.md) + +**.postcssrc.js** +```js +module.exports = { + map: 'inline' +} +``` + +> :warning: 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` + +```js +module.exports = { + to: 'path/to/dest.css' +} +``` + +### `from` + +```js +module.exports = { + from: 'path/to/src.css' +} +``` + +

Plugins

+ +### `{} || null` + +The plugin will be loaded with defaults + +```js +'postcss-plugin': {} || null +``` + +**.postcssrc.js** +```js +module.exports = { + plugins: { + 'postcss-plugin': {} || null + } +} +``` + +> :warning: `{}` must be an **empty** `{Object}` literal + +### `{Object}` + +The plugin will be loaded with given options + +```js +'postcss-plugin': { option: '', option: '' } +``` + +**.postcssrc.js** +```js +module.exports = { + plugins: { + 'postcss-plugin': { option: '', option: '' } + } +} +``` + +### `false` + +The plugin will not be loaded + +```js +'postcss-plugin': false +``` + +**.postcssrc.js** +```js +module.exports = { + plugins: { + 'postcss-plugin': false + } +} +``` + +### `Ordering` + +Plugin **execution order** is determined by declaration in the plugins section (**top-down**) + +```js +{ + 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** + +```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 + } +}) +``` + +
+ +
+ +```json +"scripts": { + "build": "NODE_ENV=production node postcss", + "start": "NODE_ENV=development node postcss" +} +``` + +```js +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)) +}) +``` + +
+ +
+ +```json +"scripts": { + "build": "NODE_ENV=production gulp", + "start": "NODE_ENV=development gulp" +} +``` + +```js +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')) +``` + +
+ +
+ +```json +"scripts": { + "build": "NODE_ENV=production webpack", + "start": "NODE_ENV=development webpack-dev-server" +} +``` + +**webpack.config.js** +```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 + 		+ +
+ François Wouts +
+ + +[npm]: https://img.shields.io/npm/v/postcss-load-config.svg +[npm-url]: https://npmjs.com/package/postcss-load-config + +[node]: https://img.shields.io/node/v/postcss-load-plugins.svg +[node-url]: https://nodejs.org/ + +[deps]: https://david-dm.org/michael-ciniawsky/postcss-load-config.svg +[deps-url]: https://david-dm.org/michael-ciniawsky/postcss-load-config + +[test]: http://img.shields.io/travis/michael-ciniawsky/postcss-load-config.svg +[test-url]: https://travis-ci.org/michael-ciniawsky/postcss-load-config + +[cover]: https://coveralls.io/repos/github/michael-ciniawsky/postcss-load-config/badge.svg +[cover-url]: https://coveralls.io/github/michael-ciniawsky/postcss-load-config + +[style]: https://img.shields.io/badge/code%20style-standard-yellow.svg +[style-url]: http://standardjs.com/ + +[chat]: https://img.shields.io/gitter/room/postcss/postcss.svg +[chat-url]: https://gitter.im/postcss/postcss + +## Security Contact + +To report a security vulnerability, please use the [Tidelift security contact]. +Tidelift will coordinate the fix and disclosure. + +[Tidelift security contact]: https://tidelift.com/security diff --git a/node_modules/postcss-load-config/package.json b/node_modules/postcss-load-config/package.json new file mode 100644 index 0000000..7e40f91 --- /dev/null +++ b/node_modules/postcss-load-config/package.json @@ -0,0 +1,48 @@ +{ + "name": "postcss-load-config", + "version": "4.0.1", + "description": "Autoload Config for PostCSS", + "main": "src/index.js", + "types": "src/index.d.ts", + "files": [ + "src" + ], + "engines": { + "node": ">= 14" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + "dependencies": { + "lilconfig": "^2.0.5", + "yaml": "^2.1.1" + }, + "peerDependencies": { + "postcss": ">=8.0.9", + "ts-node": ">=9.0.0" + }, + "peerDependenciesMeta": { + "ts-node": { + "optional": true + }, + "postcss": { + "optional": true + } + }, + "keywords": [ + "postcss", + "postcssrc", + "postcss.config.js" + ], + "author": "Michael Ciniawky ", + "contributors": [ + "Ryan Dunckel", + "Mateusz Derks", + "Dalton Santos", + "Patrick Gilday", + "François Wouts" + ], + "repository": "postcss/postcss-load-config", + "license": "MIT" +} diff --git a/node_modules/postcss-load-config/src/index.d.ts b/node_modules/postcss-load-config/src/index.d.ts new file mode 100644 index 0000000..4979220 --- /dev/null +++ b/node_modules/postcss-load-config/src/index.d.ts @@ -0,0 +1,65 @@ +// based on @types/postcss-load-config@2.0.1 +// Type definitions for postcss-load-config 2.1 +import Processor from 'postcss/lib/processor'; +import { Plugin, ProcessOptions, Transformer } from 'postcss'; +import { Options as ConfigOptions } from "lilconfig"; + +declare function postcssrc( + ctx?: postcssrc.ConfigContext, + path?: string, + options?: ConfigOptions +): Promise; + +declare namespace postcssrc { + // In the ConfigContext, these three options can be instances of the + // appropriate class, or strings. If they are strings, postcss-load-config will + // require() them and pass the instances along. + export interface ProcessOptionsPreload { + parser?: string | ProcessOptions['parser']; + stringifier?: string | ProcessOptions['stringifier']; + syntax?: string | ProcessOptions['syntax']; + } + + // The remaining ProcessOptions, sans the three above. + export type RemainingProcessOptions = Pick< + ProcessOptions, + Exclude + >; + + // Additional context options that postcss-load-config understands. + export interface Context { + cwd?: string; + env?: string; + } + + // The full shape of the ConfigContext. + export type ConfigContext = Context & + ProcessOptionsPreload & + RemainingProcessOptions; + + // Result of postcssrc is a Promise containing the filename plus the options + // and plugins that are ready to pass on to postcss. + export type ResultPlugin = Plugin | Transformer | Processor; + + export interface Result { + file: string; + options: ProcessOptions; + plugins: ResultPlugin[]; + } + + export type ConfigPlugin = Transformer | Plugin | Processor; + + export interface Config { + parser?: string | ProcessOptions['parser'] | false; + stringifier?: string | ProcessOptions['stringifier'] | false; + syntax?: string | ProcessOptions['syntax'] | false; + map?: string | false; + from?: string; + to?: string; + plugins?: Array | Record; + } + + export type ConfigFn = (ctx: ConfigContext) => Config | Promise; +} + +export = postcssrc; diff --git a/node_modules/postcss-load-config/src/index.js b/node_modules/postcss-load-config/src/index.js new file mode 100644 index 0000000..a7d1670 --- /dev/null +++ b/node_modules/postcss-load-config/src/index.js @@ -0,0 +1,179 @@ +'use strict' + +const resolve = require('path').resolve +const url = require('url') + +const config = require('lilconfig') +const yaml = require('yaml') + +const loadOptions = require('./options.js') +const loadPlugins = require('./plugins.js') + +/* istanbul ignore next */ +const interopRequireDefault = (obj) => obj && obj.__esModule ? obj : { default: obj } + +/** + * Process the result from cosmiconfig + * + * @param {Object} ctx Config Context + * @param {Object} result Cosmiconfig result + * + * @return {Object} PostCSS Config + */ +const processResult = (ctx, result) => { + const file = result.filepath || '' + let config = interopRequireDefault(result.config).default || {} + + if (typeof config === 'function') { + config = config(ctx) + } else { + config = Object.assign({}, config, ctx) + } + + if (!config.plugins) { + config.plugins = [] + } + + return { + plugins: loadPlugins(config, file), + options: loadOptions(config, file), + file + } +} + +/** + * Builds the Config Context + * + * @param {Object} ctx Config Context + * + * @return {Object} Config Context + */ +const createContext = (ctx) => { + /** + * @type {Object} + * + * @prop {String} cwd=process.cwd() Config search start location + * @prop {String} env=process.env.NODE_ENV Config Enviroment, will be set to `development` by `postcss-load-config` if `process.env.NODE_ENV` is `undefined` + */ + ctx = Object.assign({ + cwd: process.cwd(), + env: process.env.NODE_ENV + }, ctx) + + if (!ctx.env) { + process.env.NODE_ENV = 'development' + } + + return ctx +} + +const importDefault = async filepath => { + const module = await import(url.pathToFileURL(filepath).href) + return module.default +} + +const addTypeScriptLoader = (options = {}, loader) => { + const moduleName = 'postcss' + + return { + ...options, + searchPlaces: [ + ...(options.searchPlaces || []), + 'package.json', + `.${moduleName}rc`, + `.${moduleName}rc.json`, + `.${moduleName}rc.yaml`, + `.${moduleName}rc.yml`, + `.${moduleName}rc.ts`, + `.${moduleName}rc.js`, + `.${moduleName}rc.cjs`, + `.${moduleName}rc.mjs`, + `${moduleName}.config.ts`, + `${moduleName}.config.js`, + `${moduleName}.config.cjs`, + `${moduleName}.config.mjs` + ], + loaders: { + ...options.loaders, + '.yaml': (filepath, content) => yaml.parse(content), + '.yml': (filepath, content) => yaml.parse(content), + '.js': importDefault, + '.cjs': importDefault, + '.mjs': importDefault, + '.ts': loader + } + } +} + +const withTypeScriptLoader = (rcFunc) => { + return (ctx, path, options) => { + return rcFunc(ctx, path, addTypeScriptLoader(options, (configFile) => { + let registerer = { enabled () {} } + + try { + // Register TypeScript compiler instance + registerer = require('ts-node').register() + + return require(configFile) + } catch (err) { + if (err.code === 'MODULE_NOT_FOUND') { + throw new Error( + `'ts-node' is required for the TypeScript configuration files. Make sure it is installed\nError: ${err.message}` + ) + } + + throw err + } finally { + registerer.enabled(false) + } + })) + } +} + +/** + * Load Config + * + * @method rc + * + * @param {Object} ctx Config Context + * @param {String} path Config Path + * @param {Object} options Config Options + * + * @return {Promise} config PostCSS Config + */ +const rc = withTypeScriptLoader((ctx, path, options) => { + /** + * @type {Object} The full Config Context + */ + ctx = createContext(ctx) + + /** + * @type {String} `process.cwd()` + */ + path = path ? resolve(path) : process.cwd() + + return config.lilconfig('postcss', options) + .search(path) + .then((result) => { + if (!result) { + throw new Error(`No PostCSS Config found in: ${path}`) + } + + return processResult(ctx, result) + }) +}) + +/** + * Autoload Config for PostCSS + * + * @author Michael Ciniawsky @michael-ciniawsky + * @license MIT + * + * @module postcss-load-config + * @version 2.1.0 + * + * @requires comsiconfig + * @requires ./options + * @requires ./plugins + */ +module.exports = rc diff --git a/node_modules/postcss-load-config/src/options.js b/node_modules/postcss-load-config/src/options.js new file mode 100644 index 0000000..d3ef2d6 --- /dev/null +++ b/node_modules/postcss-load-config/src/options.js @@ -0,0 +1,47 @@ +'use strict' + +const req = require('./req.js') + +/** + * Load Options + * + * @private + * @method options + * + * @param {Object} config PostCSS Config + * + * @return {Object} options PostCSS Options + */ +const options = (config, file) => { + if (config.parser && typeof config.parser === 'string') { + try { + config.parser = req(config.parser, file) + } catch (err) { + throw new Error(`Loading PostCSS Parser failed: ${err.message}\n\n(@${file})`) + } + } + + if (config.syntax && typeof config.syntax === 'string') { + try { + config.syntax = req(config.syntax, file) + } catch (err) { + throw new Error(`Loading PostCSS Syntax failed: ${err.message}\n\n(@${file})`) + } + } + + if (config.stringifier && typeof config.stringifier === 'string') { + try { + config.stringifier = req(config.stringifier, file) + } catch (err) { + throw new Error(`Loading PostCSS Stringifier failed: ${err.message}\n\n(@${file})`) + } + } + + if (config.plugins) { + delete config.plugins + } + + return config +} + +module.exports = options diff --git a/node_modules/postcss-load-config/src/plugins.js b/node_modules/postcss-load-config/src/plugins.js new file mode 100644 index 0000000..6cb994b --- /dev/null +++ b/node_modules/postcss-load-config/src/plugins.js @@ -0,0 +1,85 @@ +'use strict' + +const req = require('./req.js') + +/** + * Plugin Loader + * + * @private + * @method load + * + * @param {String} plugin PostCSS Plugin Name + * @param {Object} options PostCSS Plugin Options + * + * @return {Function} PostCSS Plugin + */ +const load = (plugin, options, file) => { + try { + if ( + options === null || + options === undefined || + Object.keys(options).length === 0 + ) { + return req(plugin, file) + } else { + return req(plugin, file)(options) + } + } catch (err) { + throw new Error(`Loading PostCSS Plugin failed: ${err.message}\n\n(@${file})`) + } +} + +/** + * Load Plugins + * + * @private + * @method plugins + * + * @param {Object} config PostCSS Config Plugins + * + * @return {Array} plugins PostCSS Plugins + */ +const plugins = (config, file) => { + let plugins = [] + + if (Array.isArray(config.plugins)) { + plugins = config.plugins.filter(Boolean) + } else { + plugins = Object.keys(config.plugins) + .filter((plugin) => { + return config.plugins[plugin] !== false ? plugin : '' + }) + .map((plugin) => { + return load(plugin, config.plugins[plugin], file) + }) + } + + if (plugins.length && plugins.length > 0) { + plugins.forEach((plugin, i) => { + if (plugin.default) { + plugin = plugin.default + } + + if (plugin.postcss === true) { + plugin = plugin() + } else if (plugin.postcss) { + plugin = plugin.postcss + } + + if ( + // eslint-disable-next-line + !( + (typeof plugin === 'object' && Array.isArray(plugin.plugins)) || + (typeof plugin === 'object' && plugin.postcssPlugin) || + (typeof plugin === 'function') + ) + ) { + throw new TypeError(`Invalid PostCSS Plugin found at: plugins[${i}]\n\n(@${file})`) + } + }) + } + + return plugins +} + +module.exports = plugins diff --git a/node_modules/postcss-load-config/src/req.js b/node_modules/postcss-load-config/src/req.js new file mode 100644 index 0000000..42020c9 --- /dev/null +++ b/node_modules/postcss-load-config/src/req.js @@ -0,0 +1,10 @@ +// eslint-disable-next-line n/no-deprecated-api +const { createRequire, createRequireFromPath } = require('module') + +function req (name, rootFile) { + const create = createRequire || createRequireFromPath + const require = create(rootFile) + return require(name) +} + +module.exports = req -- cgit v1.2.3