CSS Gradient Parser

Common errors

• TypeError: parseLinearGradient is not a function

  cause Attempting to use a CommonJS `require` statement or incorrect named import syntax for an ES module-first library.
  fix Ensure you are using ES module `import` syntax: `import { parseLinearGradient } from 'css-gradient-parser';`

• Error: Invalid CSS gradient string.

  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.
  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.

• TypeError: Cannot read properties of undefined (reading 'value') - originating deep within the parsing logic

  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.
  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.

Warnings

• gotcha 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.
  Fix: Pin to exact versions in production environments. Regularly review the package's GitHub repository and documentation for API changes when upgrading.
• gotcha 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.
  Fix: Thoroughly test complex or non-standard gradient syntaxes if not using with Satori. Review Satori's documentation for any known gradient parsing specifics.
• gotcha 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.
  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.

Install

• npm install css-gradient-parser npm
• yarn add css-gradient-parser yarn
• pnpm add css-gradient-parser pnpm

Imports

• parseLinearGradient
  wrong:

  const parseLinearGradient = require('css-gradient-parser').parseLinearGradient;

  correct:

  import { parseLinearGradient } from 'css-gradient-parser';

  The library primarily uses named exports and is designed for ES modules, especially given its Node.js >= 16 requirement.
• parseRadialGradient
  wrong:

  import parseRadialGradient from 'css-gradient-parser';

  correct:

  import { parseRadialGradient } from 'css-gradient-parser';

  Only named exports are available; there is no default export.
• parseConicGradient
  wrong:

  const { parseConicGradient } = require('css-gradient-parser');

  correct:

  import { parseConicGradient } from 'css-gradient-parser';

  TypeScript types are shipped, so direct import allows for type inference and checking.

Quickstart

Demonstrates how to parse various CSS gradient types (linear, radial, conic, repeating) using their respective functions and logs the structured output.

import { parseLinearGradient, parseRadialGradient, parseConicGradient } from 'css-gradient-parser';

const linearGradientStr = 'linear-gradient(to right, red, blue 50%, yellow)';
const radialGradientStr = 'radial-gradient(circle at top left, white, black 80%)';
const conicGradientStr = 'conic-gradient(from 90deg at 25% 75%, red, orange, yellow, green, blue, indigo, violet)';
const repeatingLinearGradientStr = 'repeating-linear-gradient(45deg, red, red 5px, blue 5px, blue 10px)';

console.log('Parsing linear gradient:', linearGradientStr);
const linearResult = parseLinearGradient(linearGradientStr);
console.log(JSON.stringify(linearResult, null, 2));

console.log('\nParsing radial gradient:', radialGradientStr);
const radialResult = parseRadialGradient(radialGradientStr);
console.log(JSON.stringify(radialResult, null, 2));

console.log('\nParsing conic gradient:', conicGradientStr);
const conicResult = parseConicGradient(conicGradientStr);
console.log(JSON.stringify(conicResult, null, 2));

console.log('\nParsing repeating linear gradient:', repeatingLinearGradientStr);
const repeatingLinearResult = parseLinearGradient(repeatingLinearGradientStr);
console.log(JSON.stringify(repeatingLinearResult, null, 2));