NWSAPI

Fast CSS selectors API engine with zero dependencies that works in Node.js and browsers.

NWSAPI builds on NWMATCHER with Selectors Level 4 features such as :is(), :where(), and :has(), plus state selectors such as :open and :modal. See the selector support and compatibility notes.

Performance

Direct library comparisons on native browser DOMs, without jsdom.

Performance · Memory · File size · Inside the compiler

Install

pnpm add nwsapi

In jsdom

Plug NWSAPI into jsdom for queries and stylesheet matching. Requires nwsapi ≥ 2.3.0 and jsdom ≥ 27.

Set up the dependency and override

Add the adapter's css-tree peer dependency to package.json:

{
  "dependencies": {
    "css-tree": "^3.2.1"
  }
}

Replace <version> with the published nwsapi version you want to use.

• npm (package.json):

  {
    "overrides": {
      "@asamuzakjp/dom-selector": "npm:nwsapi@<version>"
    }
  }

• pnpm (pnpm-workspace.yaml):

  overrides:
    '@asamuzakjp/dom-selector': 'npm:nwsapi@<version>'

Install dependencies after the change. The override does not change the NWSAPI factory API or add selector support.

Use the factory in Node.js

Node.js does not provide a DOM. This example creates one with jsdom.

pnpm add nwsapi jsdom

const { JSDOM } = require('jsdom')
const createNwsapi = require('nwsapi')
const { window } = new JSDOM('<p class="item">Hello</p>')
const nw = createNwsapi(window)

const items = nw.select('.item', window.document)
window.close()

This example calls NWSAPI directly. It does not replace jsdom's selector engine.

In browser

Load src/nwsapi.js from the package:

<script src="nwsapi.js"></script>
<script>
  const items = NW.Dom.select('.item', document)
  const firstItem = NW.Dom.first('.item', document)
</script>

Replace native selector methods

install() changes selector methods such as querySelectorAll() and matches() for the page. Use it only when you want those methods to call NWSAPI.

NW.Dom.install()
// Restore the original methods when they are no longer needed.
NW.Dom.uninstall()

API

See the full API reference for all methods, options, and adapter APIs.

Contribute

Use Node.js 26 and pnpm ≥ 12.3.4 to contribute.

pnpm install
pnpm test

The install sets up WPT and Chromium for browser tests. It needs Git and network access. Node tests do not use the browser or WPT checkout.

Check changes before a push

pnpm run check
pnpm run test:package
pnpm run test:fuzz        # Bounded coverage-guided pass
pnpm run test:fuzz:replay # Replay saved inputs and crashes

Run pnpm run fix to apply lint fixes, format files, and check the result. Run pnpm run test:watch to repeat Node tests while you edit files.

Run pnpm run ci:local to test the GitHub Actions workflow locally. It needs Docker and GitHub CLI authentication. It pauses when a step fails. CI uses one Node.js 26 job.

Run browser tests and measure coverage

pnpm run test:browser # Browser regressions and media states
pnpm run test:wpt     # Web Platform Tests
pnpm run cover        # Node + WPT coverage

Coverage combines Node tests and WPT in Chromium. All four aggregate metrics exceed 95%. The CLI entry point has a separate 100% coverage assertion. The coverage command checks the minimums in .config/coverage.config.mts and updates the badge. CI also creates HTML reports. Known WPT failures remain visible in test results.

Test setup and troubleshooting → · Benchmarks →

Build the package and update dependencies

Rolldown builds JavaScript from the .mts source files and creates the minified browser file. Run pnpm run build to build the files. Run pnpm run clean to remove generated JavaScript.

pnpm pack and pnpm publish build the package first. Published files keep their existing paths, CommonJS API, browser and AMD support, and extension modules. The package does not include TypeScript source files or development tools.

Pin development dependencies in the pnpm-workspace.yaml catalog. Update pnpm-lock.yaml when dependencies change. Run pnpm run update --check to preview dependency updates. Run pnpm run update to apply updates and refresh the lockfile. Run pnpm run soak:check to verify the release-delay policy. pnpm run check includes it. Use pnpm run soak:bypass package@version for an exact, dated exception. pnpm run update removes expired exceptions, synchronizes the npm and pnpm settings, and retries failed taze lookups once. Compiler tool versions need a separate compatibility review. New dependency versions have a one-day release delay. Dependency scripts need explicit approval. Use pnpm to install this repository. npm cannot install its catalog references. CI reads Node.js and package manager versions from .config/external-tools.json.

Donate or sponsor

Sponsorship helps fund maintenance, testing, and selector support.

Sponsorship and donation options

Use GitHub Sponsors, Open Collective, or Patreon for ongoing support.

You can also use Ko-fi, Buy Me a Coffee, or Liberapay. Use IssueHunt to fund issues.

Corporate sponsors can ask about custom licensing, dedicated support, or priority fixes.