@helpfulhuman/postcss-preset
v1.1.1
Published
A tool for creating PostCSS configurations based on internal standards at Helpful Human.
Downloads
1
Readme
Helpful Human's PostCSS Presets
This library provides a default set of PostCSS plugins and configurations based on the internal standards employed at Helpful Human.
Getting Started
Install via npm
:
npm install --save-dev @helpfulhuman/postcss-preset
Usage
The buildConfig()
method allows you to quickly create the entire config needed for PostCSS.
Standard PostCSS Config
If you're using PostCSS directly with postcss-cli
command line tool, you can create a postcss.config.js
file and export the results of the buildConfig()
method. This approach is likely the best solution for adding PostCSS support to codebases where modern tools like Webpack are not available or not needed.
Note: The postcss-partial-import plugin is added when using the default
buildMode
. This means you can use@import
with relative filepaths or globs to include files in your bundled CSS, like you would with SASS or Stylus.
var preset = require("@helpfulhuman/postcss-preset");
// no arguments are required
module.exports = preset.buildConfig({
variables: {
bodyFont: "Helvetica Neue, Arial, sans-serif",
brandColor: "#CC3300",
},
});
Now you can use the postcss
command line utility to build your CSS.
postcss src/index.css --map --output public/main.css
Plugins Only
Alternatively, if you're in a situation where you don't need a full configuration for PostCSS, you can get an array of just the configured plugins using the buildPlugins()
method.
Note:
buildConfig()
invokes this function under the hood.
var preset = require("@helpfulhuman/postcss-preset");
var plugins = preset.buildPlugins({ /* options */ });
Options
Name | Type | Description
-----|------|------------
autoreset | Bool
| Enables the autoreset plugin when when set to true
. Recommended for use with CSS modules. Defaults to false
.
browsers | String[]
| An array of strings used for automatically adding vendor prefixes. See autoprefixer's browser
documentation for more information. Defaults to ["last 2 version", "ie >= 10"]
enableShortRules | Bool
| Enables the use of short rule notation when set to true
. Defaults to true
.
legacyBrowsers | Bool
| Enables broadstroke legacy browser support (like IE9) when set to true
. Defaults to false
.
buildMode | Enum
| Must be set to a value of MODE_DEFAULT
, MODE_MODULES
or MODE_WEBPACK
. Defaults to MODE_DEFAULT
.
nextCSS | Bool
| When true
, enables polyfills for future CSS features including custom properties, var()
, @apply
, variable calc()
, @custom-media
, @media
ranges, @custom-selector
, element nesting, image-set
, case-insensitive attributes, hwb()
, Level-4 hsl()
and rgb()
, gray()
, RGBA hexadecimal color notations, color()
, system-ui
fonts, font-variant
, filter()
(for SVGs), :matches
, Level-4 :not
, :any-link
, and overflow-wrap
. Defaults to true
.
optimize | Bool
| Optimizes the final output for production releases. Defaults to true
when the NODE_ENV
is set to production
.
preCSS | String[]
| Enable various preprocessor features by providing an array of features to enable. Defaults to all options: ["@import", "@mixin", "@at-root", "@lookup", "@extend"]
.
pseudoFallbacks | Bool
| Provides single colon fallbacks for ::pseudo
elements including before
, after
, first-letter
, first-line
, first-child
, last-child
, hover
, focus
, and active
in order to support older browsers when set to true
. Defaults to legacyBrowsers
' value.
remFallback | Bool
| Helps support older browsers by automatically adding a px
fallback for rules using rem
units. Defaults to legacyBrowsers
' value.
rgbaFallback | Bool
| Enables rgba()
to rgb()
fallback to be added for legacy browsers when set to true
. Defaults to legacyBrowsers
' value.
variables | Object
| Provide an object literal of variables to be injected and made globally available in your stylesheets.
$sudo
Options
Warning: It is recommended that you don't touch these unless absolutely necessary.
Not listed in the options table above is the $sudo
field that allows you to manually provide configurations to each individual plugin used by this library. Along with the standard options that each plugin supports individually, a forceEnable
feature is also available to ensure that the plugin is included with your configuration (despite the settings above).
Example
var preset = require("@helpfulhuman/postcss-preset");
module.exports = preset.buildConfig({
$sudo: {
autoreset: {
reset: {
margin: 0,
padding: 0,
borderRadius: 0,
},
},
customProperties: {
preserve: true,
},
},
});
Below is a list of all of the plugins you can configure and their corresponding key name.
Key | Plugin ----|------- partialImport | postcss-partial-import mixins | postcss-mixins advancedVars | postcss-advanced-variables autoreset | postcss-autoreset short | postcss-short customProps | postcss-custom-properties apply | postcss-apply calc | postcss-calc customMedia | postcss-custom-media mediaMinMax | postcss-media-minmax customSelectors | postcss-custom-selectors nesting | postcss-nesting atRoot | postcss-at-root propertyLookup | postcss-property-lookup extend | postcss-extend imageSet | postcss-image-set-polyfill attributeCaseInsensitive | postcss-attribute-case-insensitive colorHwb | postcss-color-hwb colorHsl | postcss-color-hsl colorRgb | postcss-color-rgb colorGray | postcss-color-gray colorHexAlpha | postcss-color-hex-alpha colorFunction | postcss-color-function fontFamilySystemUi | postcss-font-family-system-ui fontVariant | postcss-font-variant filters | pleeease-filters initial | postcss-initial pseudoElements | postcss-pseudoelements selectorMatches | postcss-selector-matches selectorNot | postcss-selector-not pseudoClassAnyLink | postcss-pseudo-class-any-link replaceOverflowWrap | postcss-replace-overflow-wrap colorRgbaFallback | postcss-color-rgba-fallback pixrem | pixrem autoprefixer | autoprefixer cssnano | cssnano