HTML5 Srcset Attribute Parser

Common errors

• TypeError: parseSrcset is not a function

  cause Attempting to use `import parseSrcset from 'parse-srcset';` when the package is a CommonJS module that exports the function directly (i.e., `module.exports = function(){...}`). ESM imports of CJS modules often wrap the default export under a `default` property, causing this error.
  fix Change the import statement to `const parseSrcset = require('parse-srcset');` in Node.js environments. If using a bundler, ensure it is configured to correctly handle CJS-ESM interoperability. For new projects in ESM, use `@prettier/parse-srcset` or `srcset`.

• ERR_REQUIRE_ESM

  cause Trying to `require()` an ES Module or importing an old CJS module into a strict ESM context where `require` is not available or explicitly disallowed.
  fix The `parse-srcset` package is CJS. Ensure your environment allows `require()` or use a bundler. For pure ESM projects, migrate to `@prettier/parse-srcset` or `srcset` which provide ESM compatibility.

• Failed parsing 'srcset' attribute value since it has an unknown descriptor.

  cause The input `srcset` string contains syntax or descriptors (e.g., unsupported combinations of `w` and `x` descriptors) that the older parser version (1.0.2) does not recognize or support due to potential updates in the HTML specification or browser implementations since its last release.
  fix Verify the `srcset` string against the WHATWG HTML specification for `srcset`. If the syntax is valid according to current specs, the parser itself is outdated. Upgrade to a modern `srcset` parsing library like `@prettier/parse-srcset` or `srcset` which are actively maintained and more likely to be spec-compliant.

Warnings

• breaking This package (albell/parse-srcset) is largely unmaintained, with its last release over a decade ago (v1.0.2). It may not support newer srcset syntaxes or edge cases introduced after its last update.
  Fix: For new projects or if encountering parsing issues with modern srcset attributes, consider using actively maintained alternatives like `@prettier/parse-srcset` or `srcset`.
• gotcha The `parse-srcset` package is a CommonJS module. Directly using `import parseSrcset from 'parse-srcset'` in an ES Module context without proper transpilation or bundler configuration will likely result in runtime errors (e.g., `TypeError: parseSrcset is not a function` or issues with default exports).
  Fix: In Node.js ES Module environments, use `const parseSrcset = require('parse-srcset');` or rely on bundlers like Webpack/Rollup to handle CJS-ESM interoperability. For pure ESM, prefer the `@prettier/parse-srcset` fork or the `srcset` package which offer native ESM support.
• deprecated The original `parse-srcset` library lacks modern tooling and features like TypeScript declarations. While functional, its maintenance status and lack of updates mean it will not receive bug fixes or performance improvements.
  Fix: Migrate to `srcset` (e.g., `npm install srcset`) or `@prettier/parse-srcset` (e.g., `npm install @prettier/parse-srcset`) for TypeScript support, active development, and potentially better performance/spec compliance.
• gotcha Older parsers might not fully align with the most recent `srcset` specifications or common browser interpretations for complex or malformed inputs, potentially leading to 'Failed parsing srcset attribute' errors or incorrect output for specific descriptors like `w` and `x` in combination.
  Fix: Thoroughly test parsing results with various `srcset` inputs, especially those involving modern descriptors or edge cases. Consider using a more actively maintained library for guaranteed spec compliance.

Install

• npm install parse-srcset npm
• yarn add parse-srcset yarn
• pnpm add parse-srcset pnpm

Imports

• parseSrcset
  wrong:

  import parseSrcset from 'parse-srcset';

  correct:

  const parseSrcset = require('parse-srcset');

  This package (v1.0.2) is a CommonJS module. Use `require()` for Node.js environments. Attempting `import ... from` will likely result in a `TypeError` if not handled by a bundler.
• parseSrcset
  wrong:

  const parseSrcset = require('parse-srcset');

  correct:

  import parseSrcset from '@prettier/parse-srcset';

  While this entry focuses on `parse-srcset` (albell's), a popular, actively maintained fork by Prettier exists under `@prettier/parse-srcset`. This fork uses modern ESM syntax and is recommended for new projects.
• parse
  wrong:

  import parse from 'parse-srcset';

  correct:

  import { parse } from 'srcset';

  Another actively maintained alternative, `srcset`, provides both parsing and stringifying functionality. Its primary parsing function is named `parse` and is typically imported as a named export.

Quickstart

This quickstart demonstrates how to parse a standard HTML `srcset` string using `require()` and then iterates through the resulting array of image source objects, logging their URLs and descriptors (density or width).

const parseSrcset = require('parse-srcset');

const srcsetString = 'elva-fairy-320w.jpg, elva-fairy-480w.jpg 1.5x, elva-fairy-640w.jpg 2x';
const parsed = parseSrcset(srcsetString);

console.log('Original srcset:', srcsetString);
console.log('Parsed output:');
parsed.forEach(item => {
  console.log(`- URL: ${item.url}, Descriptor: ${item.density || (item.width ? item.width + 'w' : '')}`);
});

// Example with width descriptors (though this old version might interpret differently)
const widthSrcsetString = 'image-160.jpg 160w, image-320.jpg 320w, image-640.jpg 640w';
const parsedWidth = parseSrcset(widthSrcsetString);

console.log('\nOriginal srcset (width descriptors):', widthSrcsetString);
console.log('Parsed output (width descriptors):');
parsedWidth.forEach(item => {
  console.log(`- URL: ${item.url}, Descriptor: ${item.width ? item.width + 'w' : item.density}`);
});