node-detective-postcss

Find the dependencies of a CSS file (PostCSS dialect)

Supports @import and @value ... from. Absolute and protocol-relative URLs are automatically filtered out.

The AST is generated using postcss and postcss-values-parser.

Installation

npm install detective-postcss

postcss must be installed separately as a peer dependency:

npm install postcss

Usage

// ESM
import { readFileSync } from 'node:fs';
import detective from 'detective-postcss';
// CommonJS
const { readFileSync } = require('node:fs');
const detective = require('detective-postcss');

const content = readFileSync('styles.css', 'utf8');

// Returns an array of imported file paths (e.g. ['foo.css', 'bar.css'])
const dependencies = detective(content);

// Also include url() references (images, fonts, etc.) found in declarations
const allDependencies = detective(content, { url: true });

API

detective(src, options?)

Returns string[] - the list of local dependency paths found in the source.

Throws detective.MalformedCssError if src cannot be parsed.

What is detected

Absolute URLs (https://...) and protocol-relative URLs (//...) are always ignored.

Related

This is the CSS (PostCSS dialect) counterpart to:

• detective-cjs - CommonJS
• detective-amd - AMD
• detective-es6 - ES modules
• detective-sass - Sass
• detective-scss - SCSS

Releasing

1. Ensure CI is green on main.
2. Preview what would be included in the package without publishing: npm pack --dry-run.
3. Bump the version following semver (this also creates the vX.Y.Z tag): npm version <patch|minor|major>.
4. Push the commit and tag: git push --follow-tags.
5. Create (or draft) a GitHub release from that vX.Y.Z tag, then Publish it.
6. Publishing the release triggers npm-publish (release.published), which runs npm ci and npm publish --provenance.

License

MIT