{"id":11575,"library":"postcss-functions","title":"PostCSS JavaScript Functions","description":"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.","status":"active","version":"4.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/andyjansson/postcss-functions","tags":["javascript","postcss","postcss-plugin","function","functions"],"install":[{"cmd":"npm install postcss-functions","lang":"bash","label":"npm"},{"cmd":"yarn add postcss-functions","lang":"bash","label":"yarn"},{"cmd":"pnpm add postcss-functions","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for PostCSS processing.","package":"postcss","optional":false}],"imports":[{"note":"The plugin factory is a default export.","wrong":"import { functions } from 'postcss-functions';","symbol":"functions","correct":"import functions from 'postcss-functions';"},{"note":"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+.","wrong":"const postcss = require('postcss');","symbol":"postcss","correct":"import postcss from 'postcss';"},{"note":"When using TypeScript, import types like `ProcessOptions` from the 'postcss' package for better type checking.","symbol":"ProcessOptions","correct":"import { ProcessOptions } from 'postcss';"}],"quickstart":{"code":"import fs from 'fs';\nimport postcss from 'postcss';\nimport functions from 'postcss-functions';\n\nconst inputCss = `\nbody {\n  /* Example using a custom JS function */\n  background-color: myCustomColor('darken', 'blue', 0.2);\n}\n.foo {\n  color: darken(red, 0.1);\n}\n`;\n\n// Define custom JavaScript functions to be exposed to PostCSS\nconst customFunctions = {\n  myCustomColor: (mode, color, amount) => {\n    // A more complex example, could involve external libraries\n    if (mode === 'darken') {\n      // Simplified darkening logic for demonstration\n      return `rgba(0, 0, ${Math.floor(255 * (1 - parseFloat(amount)))}, 1)`;\n    }\n    return color;\n  },\n  darken: (value, frac) => {\n    // Basic example of a function, similar to the README\n    const darkenFactor = 1 - parseFloat(frac);\n    // In a real scenario, use a color manipulation library\n    // For demo, just return a string\n    return `rgba(0, 0, ${Math.floor(255 * darkenFactor)}, 1)`;\n  }\n};\n\npostcss()\n  .use(functions({ functions: customFunctions }))\n  .process(inputCss, { from: undefined })\n  .then((result) => {\n    console.log('Processed CSS:\\n', result.css);\n  })\n  .catch((error) => {\n    console.error('PostCSS processing failed:', error);\n  });\n","lang":"typescript","description":"Demonstrates basic setup, defining custom JavaScript functions, and applying them within CSS using postcss-functions."},"warnings":[{"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.","message":"The `glob` feature, which allowed specifying function files via glob patterns, was removed in version 4.0.0. This change reduces package size and dependencies.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure all exposed JavaScript functions explicitly return a string that represents a valid CSS value (e.g., 'red', '10px', 'rgb(0,0,0)').","message":"Functions 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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);`.","message":"Arguments 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import functions from 'postcss-functions';` and then calling it like `postcss().use(functions({ /* options */ }))`.","cause":"The `postcss-functions` module is imported incorrectly, or the imported value is not invoked as a function.","error":"TypeError: functions is not a function"},{"fix":"Install `postcss` alongside `postcss-functions`: `npm install --save-dev postcss postcss-functions` or `yarn add --dev postcss postcss-functions`.","cause":"The `postcss` peer dependency is not installed.","error":"Error: Cannot find module 'postcss'"},{"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.","cause":"A function called in CSS was not provided in the `functions` option or has a misspelled name.","error":"CSS: Unknown word at line X, column Y (e.g., `background-color: unknownFunction(arg);`)"}],"ecosystem":"npm"}