Polished

Common errors

• TypeError: (0 , polished__WEBPACK_IMPORTED_MODULE_2__.lighten) is not a function

  cause 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.
  fix Change `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.

  cause TypeScript's module resolution failing to locate the package's type definitions.
  fix Ensure `"moduleResolution": "node"` is set within the `compilerOptions` in your `tsconfig.json`.

• ReferenceError: require is not defined in ES module scope

  cause 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.
  fix Switch to ESM named imports: `import { functionName } from 'polished';`.

Warnings

• gotcha To 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.
  Fix: Refactor your import statements to use named imports for each function you utilize from the library.
• breaking The `scarf` analytics package was removed due to yarn incompatibilities and GDPR compliance concerns. This change addresses potential supply chain and privacy issues.
  Fix: No 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.
• gotcha When using Polished with TypeScript, ensure your `tsconfig.json` includes `"moduleResolution": "node"` to correctly resolve module imports and type definitions.
  Fix: Add or verify `"moduleResolution": "node"` within the `compilerOptions` in your `tsconfig.json`.
• gotcha If 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.
  Fix: Add `.*/node_modules/polished/.*` to the `[ignore]` section of your `.flowconfig`.
• gotcha Using 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`.
  Fix: Install and configure `babel-plugin-transform-object-rest-spread` or a compatible Babel preset in your project's Babel configuration.
• breaking Versions 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.
  Fix: Update `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.

Install

• npm install polished npm
• yarn add polished yarn
• pnpm add polished pnpm

Imports

• lighten
  wrong:

  import polished from 'polished'; polished.lighten(...)

  correct:

  import { lighten } from 'polished'

  Polished functions should be imported individually for optimal tree-shaking and bundle size reduction. Avoid default or star imports.
• fluidRange
  wrong:

  const { fluidRange } = require('polished')

  correct:

  import { fluidRange } from '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
  wrong:

  import * as polished from 'polished'; polished.rgba(...)

  correct:

  import { rgba } from 'polished'

  Importing the entire library via `* as polished` prevents effective tree-shaking, leading to larger bundle sizes than necessary. Stick to named imports.

Quickstart

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);