{"id":15581,"library":"css-gradient-parser","title":"CSS Gradient Parser","description":"css-gradient-parser is a JavaScript/TypeScript library designed to parse CSS gradient strings, specifically developed to extend gradient feature support within the Vercel Satori library. Currently at version 0.0.18, it provides distinct functions for parsing linear, radial, and conic gradients, including their `repeating` variations. As a pre-1.0 project, its release cadence is likely irregular, with features and API potentially evolving rapidly. Its primary differentiator is its targeted integration with Satori, aiming to bridge the gap in gradient rendering capabilities for server-side image generation, though it can be used independently for general CSS gradient parsing needs.","status":"active","version":"0.0.18","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install css-gradient-parser","lang":"bash","label":"npm"},{"cmd":"yarn add css-gradient-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add css-gradient-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses named exports and is designed for ES modules, especially given its Node.js >= 16 requirement.","wrong":"const parseLinearGradient = require('css-gradient-parser').parseLinearGradient;","symbol":"parseLinearGradient","correct":"import { parseLinearGradient } from 'css-gradient-parser';"},{"note":"Only named exports are available; there is no default export.","wrong":"import parseRadialGradient from 'css-gradient-parser';","symbol":"parseRadialGradient","correct":"import { parseRadialGradient } from 'css-gradient-parser';"},{"note":"TypeScript types are shipped, so direct import allows for type inference and checking.","wrong":"const { parseConicGradient } = require('css-gradient-parser');","symbol":"parseConicGradient","correct":"import { parseConicGradient } from 'css-gradient-parser';"}],"quickstart":{"code":"import { parseLinearGradient, parseRadialGradient, parseConicGradient } from 'css-gradient-parser';\n\nconst linearGradientStr = 'linear-gradient(to right, red, blue 50%, yellow)';\nconst radialGradientStr = 'radial-gradient(circle at top left, white, black 80%)';\nconst conicGradientStr = 'conic-gradient(from 90deg at 25% 75%, red, orange, yellow, green, blue, indigo, violet)';\nconst repeatingLinearGradientStr = 'repeating-linear-gradient(45deg, red, red 5px, blue 5px, blue 10px)';\n\nconsole.log('Parsing linear gradient:', linearGradientStr);\nconst linearResult = parseLinearGradient(linearGradientStr);\nconsole.log(JSON.stringify(linearResult, null, 2));\n\nconsole.log('\\nParsing radial gradient:', radialGradientStr);\nconst radialResult = parseRadialGradient(radialGradientStr);\nconsole.log(JSON.stringify(radialResult, null, 2));\n\nconsole.log('\\nParsing conic gradient:', conicGradientStr);\nconst conicResult = parseConicGradient(conicGradientStr);\nconsole.log(JSON.stringify(conicResult, null, 2));\n\nconsole.log('\\nParsing repeating linear gradient:', repeatingLinearGradientStr);\nconst repeatingLinearResult = parseLinearGradient(repeatingLinearGradientStr);\nconsole.log(JSON.stringify(repeatingLinearResult, null, 2));","lang":"typescript","description":"Demonstrates how to parse various CSS gradient types (linear, radial, conic, repeating) using their respective functions and logs the structured output."},"warnings":[{"fix":"Pin to exact versions in production environments. Regularly review the package's GitHub repository and documentation for API changes when upgrading.","message":"As a pre-1.0 release (version 0.0.18), the API is subject to breaking changes in minor or even patch versions. Consult the project's changelog for updates.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Thoroughly test complex or non-standard gradient syntaxes if not using with Satori. Review Satori's documentation for any known gradient parsing specifics.","message":"The library is specifically designed to provide parsing capabilities for Vercel Satori. While generally usable, it might have specific behaviors, limitations, or edge cases optimized for Satori's rendering pipeline that may not be ideal for other use cases.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Ensure your Node.js environment is version 16 or newer. For browser usage, configure your build tools (e.g., Babel, esbuild, Webpack) to transpile to a compatible JavaScript target.","message":"The package's `engines` field specifies `node: \">=16\"`. Running in older Node.js versions or highly constrained legacy browser environments without proper transpilation may lead to unexpected errors or lack of functionality.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you are using ES module `import` syntax: `import { parseLinearGradient } from 'css-gradient-parser';`","cause":"Attempting to use a CommonJS `require` statement or incorrect named import syntax for an ES module-first library.","error":"TypeError: parseLinearGradient is not a function"},{"fix":"Verify that your gradient string is valid CSS syntax. Check the library's README for supported gradient features and report any valid but unparsed gradients as an issue.","cause":"The input string provided to a parser function (e.g., `parseLinearGradient`) does not conform to expected CSS gradient syntax, or includes features not yet supported by the parser.","error":"Error: Invalid CSS gradient string."},{"fix":"Debug the exact input gradient string that causes the error. Simplify the gradient to isolate the problematic part. If the gradient is standard CSS, consider submitting a bug report to the library's maintainers with the problematic string.","cause":"This often occurs when a subtly malformed or highly unconventional gradient string causes the parser to produce an incomplete or incorrectly structured intermediate result, which then breaks subsequent property access.","error":"TypeError: Cannot read properties of undefined (reading 'value') - originating deep within the parsing logic"}],"ecosystem":"npm"}