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