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

const fs = require('node:fs');
const detective = require('detective-postcss');

const content = fs.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 });

TypeScript / ESM:

import detective = require('detective-postcss');

const dependencies = detective(content);
const allDependencies = detective(content, { url: true });

API

detective(src, options?)

Parameter	Type	Required	Description
src	string	Yes	CSS source code to analyse
options.url	boolean	No	When true, also extracts url() references from declarations (e.g. background, src, cursor). Defaults to false.

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

Throws detective.MalformedCssError if src cannot be parsed.

What is detected

Syntax	Example	Detected by default
@import "file.css"	@import "theme.css"	yes
@import url(file.css)	@import url(print.css)	yes
@value x from "file.css"	@value primary from 'colors.css'	yes
url() in declarations	background: url(bg.png)	only with { url: true }

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