Registry / devops / postcss-functions

postcss-functions

library4.0.2jsnpmunverified

postcss-functions is a PostCSS plugin that allows developers to expose JavaScript functions for direct invocation within CSS files during the build process. It enables dynamic value generation, complex calculations, and programmatic transformations of CSS properties, extending the capabilities of standard CSS. The current stable version is 4.0.2, maintaining compatibility with PostCSS v8.x. While release cadence isn't strictly defined, major version updates (like 4.0.0) indicate significant changes and active maintenance. Its key differentiator is providing a clean bridge between JavaScript logic and CSS styling without relying on preprocessors, allowing for highly customized and reusable CSS utility functions defined in JavaScript.

devops

npm install postcss-functions

github ↗package ↗

INSTALL

IMPORT

SIG · POSTCSS-FUNCTIONS

postcss-functions

devopsjavascriptv4.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

functions

✓ import functions from 'postcss-functions';

✗ import { functions } from 'postcss-functions';

The plugin factory is a default export.

postcss

✓ import postcss from 'postcss';

✗ const postcss = require('postcss');

This package, and PostCSS itself, are primarily used in ESM contexts for modern build setups. While CJS is possible, ESM is the idiomatic way for `postcss` v8+.

ProcessOptions

✓ import { ProcessOptions } from 'postcss';

When using TypeScript, import types like `ProcessOptions` from the 'postcss' package for better type checking.

Demonstrates basic setup, defining custom JavaScript functions, and applying them within CSS using postcss-functions.

import fs from 'fs'; import postcss from 'postcss'; import functions from 'postcss-functions'; const inputCss = ` body { /* Example using a custom JS function */ background-color: myCustomColor('darken', 'blue', 0.2); } .foo { color: darken(red, 0.1); } `; // Define custom JavaScript functions to be exposed to PostCSS const customFunctions = { myCustomColor: (mode, color, amount) => { // A more complex example, could involve external libraries if (mode === 'darken') { // Simplified darkening logic for demonstration return `rgba(0, 0, ${Math.floor(255 * (1 - parseFloat(amount)))}, 1)`; } return color; }, darken: (value, frac) => { // Basic example of a function, similar to the README const darkenFactor = 1 - parseFloat(frac); // In a real scenario, use a color manipulation library // For demo, just return a string return `rgba(0, 0, ${Math.floor(255 * darkenFactor)}, 1)`; } }; postcss() .use(functions({ functions: customFunctions })) .process(inputCss, { from: undefined }) .then((result) => { console.log('Processed CSS:\n', result.css); }) .catch((error) => { console.error('PostCSS processing failed:', error); });

Debug

Known issues

breakingThe `glob` feature, which allowed specifying function files via glob patterns, was removed in version 4.0.0. This change reduces package size and dependencies.

fix

Instead of using glob patterns, manually `import` your JavaScript function files into your PostCSS configuration file and pass them directly to the `functions` option object. You can use a separate globbing library like `fast-glob` in your build script if you still require dynamic loading.

affects: >=4.0.0

gotchaFunctions defined in the `functions` option must return valid CSS values. If a function returns an invalid or non-string value (e.g., `undefined`, `null`, a complex object), PostCSS may output unexpected CSS or throw an error during processing.

fix

Ensure all exposed JavaScript functions explicitly return a string that represents a valid CSS value (e.g., 'red', '10px', 'rgb(0,0,0)').

affects: >=1.0.0

gotchaArguments passed to CSS functions from `postcss-functions` are always strings. If you expect numbers or booleans, you must explicitly parse them within your JavaScript function.

fix

Inside your JavaScript function, use `parseFloat()`, `parseInt()`, `JSON.parse()`, or other conversion methods as needed to handle string arguments, e.g., `const value = parseFloat(arg);`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: functions is not a function

The `postcss-functions` module is imported incorrectly, or the imported value is not invoked as a function.

fix

Ensure you are using `import functions from 'postcss-functions';` and then calling it like `postcss().use(functions({ /* options */ }))`.

Error: Cannot find module 'postcss'

The `postcss` peer dependency is not installed.

fix

Install `postcss` alongside `postcss-functions`: `npm install --save-dev postcss postcss-functions` or `yarn add --dev postcss postcss-functions`.

CSS: Unknown word at line X, column Y (e.g., `background-color: unknownFunction(arg);`)

A function called in CSS was not provided in the `functions` option or has a misspelled name.

fix

Verify that the function name used in your CSS matches the key in the `functions` object passed to `postcss-functions`, and that the function object is correctly passed to the plugin.

Upgrade

Version history

4.0.2latest on npm

Audit

Dependencies

postcssrequiredRequired peer dependency for PostCSS processing.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/andyjansson/postcss-functions ↗

packagehttps://www.npmjs.com/package/postcss-functions ↗