Registry / serialization / css-gradient-parser

css-gradient-parser

library0.0.18jsnpmunverified

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.

serialization

npm install css-gradient-parser

package ↗

INSTALL

IMPORT

SIG · CSS-GRADIENT-PARSE

css-gradient-parser

serializationjavascriptv0.0.18

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.

parseLinearGradient

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

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

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

parseRadialGradient

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

✗ import parseRadialGradient from 'css-gradient-parser';

Only named exports are available; there is no default export.

parseConicGradient

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

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

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

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

Debug

Known issues

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

affects: <1.0.0

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

affects: >=0.0.1

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

affects: >=0.0.1

Errors

Common errors & fixes

TypeError: parseLinearGradient is not a function

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.

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

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.

Upgrade

Version history

0.0.18latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/css-gradient-parser ↗