Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
lighten
✓ import { lighten } from 'polished'
✗ import polished from 'polished'; polished.lighten(...)
Polished functions should be imported individually for optimal tree-shaking and bundle size reduction. Avoid default or star imports.
fluidRange
✓ import { fluidRange } from 'polished'
✗ const { fluidRange } = require('polished')
While CommonJS `require` might work in some environments, Polished is designed for ESM imports to leverage modern tooling features like tree-shaking. TypeScript users should ensure `moduleResolution: 'node'` in `tsconfig.json`.
rgba
✓ import { rgba } from 'polished'
✗ import * as polished from 'polished'; polished.rgba(...)
Importing the entire library via `* as polished` prevents effective tree-shaking, leading to larger bundle sizes than necessary. Stick to named imports.
Demonstrates core Polished functionalities including color manipulation (lighten, darken, rgba), responsive design helpers (fluidRange), and unit conversion (em). It highlights the recommended named import pattern.
import { lighten, darken, rgba, fluidRange, em } from 'polished';
// Example: Color manipulation
const baseColor = '#663399'; // A deep purple
const lightenedColor = lighten(0.2, baseColor);
const darkenedColor = darken(0.1, baseColor);
const transparentColor = rgba(baseColor, 0.5);
console.log('Original color:', baseColor);
console.log('Lightened color:', lightenedColor);
console.log('Darkened color:', darkenedColor);
console.log('Transparent color (50% opacity):', transparentColor);
// Example: Responsive typography with fluidRange
// Defines a font size that scales between 16px and 20px
// within viewport widths of 400px to 1200px.
const responsiveFontProps = fluidRange(
{ prop: 'font-size', fromSize: '16px', toSize: '20px' },
'400px',
'1200px'
);
console.log('\nResponsive font properties (for CSS-in-JS):');
console.log(responsiveFontProps);
// Example: Em unit conversion
const emValue = em(16, 14); // 16px based on a 14px root font size
console.log('\n16px converted to em (base 14px):', emValue); // '1.1428571428571428em'
// Demonstrate functional composition, a key concept for Polished
// Assuming a 'compose' utility from a library like Ramda or a custom one
// import { compose } from 'ramda';
// const makeBrighterAndMoreTransparent = compose(
// (color: string) => lighten(0.1, color),
// (color: string) => rgba(color, 0.8)
// );
// const newColor = makeBrighterAndMoreTransparent('#FF0000');
// console.log('\nComposed color (brighter and more transparent red):', newColor);
Debug
Known issues
gotchaTo ensure optimal bundle size, always use named imports for individual Polished functions (e.g., `import { lighten } from 'polished'`). Avoid `import * as polished from 'polished'` or `import polished from 'polished'` as these prevent tree-shaking.fixRefactor your import statements to use named imports for each function you utilize from the library.
affects: >=1.0.0
breakingThe `scarf` analytics package was removed due to yarn incompatibilities and GDPR compliance concerns. This change addresses potential supply chain and privacy issues.fixNo direct action is required from users, but be aware of the removal of this internal dependency if you had specific monitoring setups that might have inadvertently relied on it. Update to v4.1.1+ or v3.7.1+ LTS to ensure removal.
affects: >=4.1.1, >=3.7.1
gotchaWhen using Polished with TypeScript, ensure your `tsconfig.json` includes `"moduleResolution": "node"` to correctly resolve module imports and type definitions.fixAdd or verify `"moduleResolution": "node"` within the `compilerOptions` in your `tsconfig.json`.
affects: >=1.0.0
gotchaIf you encounter Flow type errors originating from the `polished` package, it may be due to Flow version incompatibilities. You can ignore Polished's source in your Flow configuration.fixAdd `.*/node_modules/polished/.*` to the `[ignore]` section of your `.flowconfig`.
affects: >=1.0.0
gotchaUsing object spread properties (e.g., `{ ...other }`) within your styles that integrate with Polished requires a Babel plugin such as `transform-object-rest-spread` or a preset like `stage-3`.fixInstall and configure `babel-plugin-transform-object-rest-spread` or a compatible Babel preset in your project's Babel configuration.
affects: >=1.0.0
breakingVersions prior to v4.3.1 might experience incompatibility issues with later versions of Rollup due to the `annotate-pure-calls` plugin. This was resolved in v4.3.1.fixUpdate `polished` to v4.3.1 or newer if you are using Rollup in your build pipeline and encountering related issues. Alternatively, ensure your Rollup version is compatible with older Polished versions.
affects: <4.3.1
Errors
Common errors & fixes
TypeError: (0 , polished__WEBPACK_IMPORTED_MODULE_2__.lighten) is not a function
Attempting to use a Polished function via a default or star import, which prevents bundlers like Webpack from tree-shaking and correctly exposing the named export at runtime.
fixChange `import * as polished from 'polished'` or `import polished from 'polished'` to `import { lighten } from 'polished'` for the specific function being used. TS2307: Cannot find module 'polished' or its corresponding type declarations.
TypeScript's module resolution failing to locate the package's type definitions.
fixEnsure `"moduleResolution": "node"` is set within the `compilerOptions` in your `tsconfig.json`.
ReferenceError: require is not defined in ES module scope
Using CommonJS `require('polished')` syntax in an environment configured for ECMAScript Modules (ESM), typically in modern Node.js projects with `"type": "module"` in `package.json` or in browser environments after bundling.
fixSwitch to ESM named imports: `import { functionName } from 'polished';`. Audit
Dependencies
No dependency data recorded yet.