Skip to content

README.md

Latest commit

 

History

History
94 lines (63 loc) · 4.18 KB

README.md

File metadata and controls

94 lines (63 loc) · 4.18 KB

node-detective-postcss

build npm version npm downloads

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:

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