xpath-to-css

library1.2.0jsnpmunverified

xpath-to-css is a JavaScript utility package designed to translate XPath expressions into equivalent CSS selectors. Originally conceived in Python for the `cssify` project by santiycr and later adapted to a JavaScript gist by Dither, this package by Jonathan Svenheden provides an npm-published, ES2015 and CommonJS-compatible solution. It is currently at version 1.2.0, with a release cadence that is likely infrequent, reflecting its stable utility nature rather than active feature development, given its last update was over two years ago. Its core differentiation lies in providing a readily accessible and battle-tested conversion tool for a specific web scraping and automation need, handling various common XPath patterns like ID, class, attribute, and positional selectors. Developers leverage it to bridge between systems that prefer CSS selectors (e.g., Playwright, Puppeteer) and sources that provide XPath (e.g., some browser developer tools, legacy systems).

serialization

npm install xpath-to-css

github ↗package ↗

INSTALL

IMPORT

SIG · XPATH-TO-CSS

xpath-to-css

serializationjavascriptv1.2.0

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.

xPathToCss

✓ import xPathToCss from 'xpath-to-css';

✗ import { xPathToCss } from 'xpath-to-css';

The primary conversion function is exported as a default export in ES Modules.

xPathToCss (CommonJS)

✓ const xPathToCss = require('xpath-to-css');

✗ const { xPathToCss } = require('xpath-to-css');

For CommonJS environments, `require` directly returns the default-exported function, no `.default` or destructuring is needed.

Demonstrates how to import the `xPathToCss` function and convert a complex XPath expression to its CSS selector equivalent, along with simpler examples.

import xPathToCss from 'xpath-to-css'; const xPath = '//div[@id="foo"][2]/span[@class="bar"]//a[contains(@class, "baz")]//img[1]'; const css = xPathToCss(xPath); console.log(css); // => 'div#foo:nth-of-type(2) > span.bar a[class*=baz] img:first-of-type' const simpleXPath = '//h1'; const simpleCss = xPathToCss(simpleXPath); console.log(simpleCss); // => 'h1' const attributeXPath = '//input[@type="text"]'; const attributeCss = xPathToCss(attributeXPath); console.log(attributeCss); // => 'input[type="text"]'

Debug

Known issues

gotchaNot all advanced or complex XPath expressions can be directly translated into equivalent CSS selectors. The utility might return an error or an incomplete selector for XPath features like parent traversal (`..`), preceding-sibling, or complex text content matching not based on `contains()`.

fix

Simplify the XPath expression if possible, or manually craft a CSS selector or alternative locator strategy for the problematic part. Understand the limitations of CSS selectors compared to XPath.

affects: >=1.0.0

gotchaThe conversion process is synchronous. While generally fast for typical XPath expressions, for applications requiring high performance or processing a very large number of extremely complex XPath expressions, this might introduce blocking delays.

fix

Consider batching conversions, offloading to a worker thread for very high-volume scenarios, or pre-converting known XPaths during application startup if performance becomes an issue.

affects: >=1.0.0

gotchaThe package appears to be in maintenance mode, with its last update over two years ago and no recent releases. While stable for its current functionality, new XPath features or complex edge cases introduced in newer browser standards may not be supported or actively developed.

fix

Review the package's GitHub issues for known limitations or unaddressed features before relying on it for cutting-edge XPath patterns. Be prepared to contribute fixes or fork if specific unsupported features are critical.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: xPathToCss is not a function

Attempting to import `xPathToCss` as a named export (`import { xPathToCss } from 'xpath-to-css';`) when it is a default export, or using incorrect CommonJS destructuring.

fix

For ES Modules, use `import xPathToCss from 'xpath-to-css';`. For CommonJS, use `const xPathToCss = require('xpath-to-css');`.

Error: Unsupported XPath expression: //some/complex/xpath[contains(text(), 'value')]/parent::*

The provided XPath expression uses features or patterns that the `xpath-to-css` library cannot translate into a CSS selector. Not all XPath constructs have direct CSS equivalents (e.g., parent traversal, complex text matching functions).

fix

Simplify the XPath expression if possible to use only commonly supported features (IDs, classes, attributes, direct child/descendant, position). If simplification is not feasible, consider manually crafting a CSS selector or using alternative element location strategies for the problematic part. Verify if the XPath expression is valid and if a CSS equivalent can exist.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/svenheden/xpath-to-css ↗

packagehttps://www.npmjs.com/package/xpath-to-css ↗