precinct

Unleash the detectives

Uses the appropriate detective to find the dependencies of a file or its AST.

Supports:

• JavaScript modules: AMD, CommonJS, ES6
• TypeScript
• CSS preprocessors: Sass, Scss, Less, Stylus
• CSS (PostCSS)
• Vue

Install

npm install precinct

Quick start

// ESM
import fs from 'node:fs';
import precinct from 'precinct';
// CommonJS
const fs = require('node:fs');
const { default: precinct } = require('precinct');

const content = fs.readFileSync('myFile.js', 'utf8');

// From source content or an AST
const deps = precinct(content);

// Or directly from a file path
const deps2 = precinct.paperwork('styles.scss');

API

precinct(content, options?)

Returns an array of dependency strings discovered in content. content may be a source string or an already-parsed AST.

| Option | Type | Default | Notes | |---|---|---|---| | type | string | inferred from source | Forces a specific detective. See Supported types. | | walker | object | - | Passed through to the underlying node-source-walk instance - e.g. { allowImportExportEverywhere: true }, or { parser: myCustomParser } to swap in a parser with a .parse(src, opts) method. | | amd.skipLazyLoaded | boolean | false | Omit lazy-loaded (inner-require) dependencies in AMD files. | | es6.mixedImports | boolean | false | Return both ES6 and CommonJS imports from a file that mixes the two. Works for any format that contains an ES6 import. | | css.url | boolean | false | Include url() references (images, fonts, etc.) in CSS output. | | [type] | object | - | Any other key matching a module type is forwarded to that detective as its options bag. |

Side channel: precinct.ast holds the last AST produced (or null when parsing failed).

Example

precinct(content, {
  type: 'amd',
  amd: {
    skipLazyLoaded: true
  }
});

precinct(content, {
  walker: {
    allowImportExportEverywhere: true
  }
});

// Non-JS content
precinct(scssSource, { type: 'scss' });
precinct(stylusSource, { type: 'stylus' });

precinct.paperwork(filename, options?)

Reads the file at filename and returns an array of its dependencies. The module type is inferred from the file extension (see below). Accepts every option precinct() does, plus the two below.

| Option | Type | Default | Notes | |---|---|---|---| | includeCore | boolean | true | Set to false to strip Node.js core modules (fs, path, node:fs, ...) from the result. | | fileSystem | { readFileSync(path, encoding): string } | node:fs | An alternative fs implementation used to read filename. Only readFileSync(path, 'utf8') is required. | | walker, amd, es6, css, [type] | - | - | Same as precinct() - all detective options are forwarded. |

Example

// ESM
import { paperwork } from 'precinct';
// CommonJS
const { paperwork } = require('precinct');

const deps = paperwork('myFile.js');
const deps2 = paperwork('styles.scss');
const deps3 = paperwork('app.ts', { includeCore: false });

Supported types

Accepted values for the type option:

| Value | Detective | |---|---| | amd | detective-amd | | cjs, commonjs | detective-cjs | | css | detective-postcss | | es6, esm, mjs | detective-es6 | | less | @dependents/detective-less | | sass | detective-sass | | scss | detective-scss | | stylus | detective-stylus | | ts | detective-typescript | | tsx | detective-typescript (tsx variant) | | vue | detective-vue2 |

paperwork() infers the type from the filename extension; .styl maps to stylus and .cjs maps to commonjs. Any other extension becomes the type with the leading dot stripped. .js and .jsx are sniffed at the source level rather than by extension.

CLI

npm install -g precinct
precinct [options] <filename>

| Flag | Description | |---|---| | -t, --type <type> | Force a module type (see Supported types). | | --es6-mixed-imports | Collect both ES6 and CommonJS imports in the same file. | | -V, --version | Print version. | | -h, --help | Print help. |

License

MIT