# filing-cabinet

> Find files based on partial paths

Latest version **6.0.0** (published 2026-05-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install filing-cabinet
pnpm add filing-cabinet
yarn add filing-cabinet
bun add filing-cabinet
```

Provides the command `filing-cabinet`.

## Health

**Score 63/100 (C)** — status: active.

Positive: has types package; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 6.0.0 |
| Published | 2026-05-19 |
| First published | 2015-08-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/filing-cabinet) |
| Module format | ESM |
| Node | >=20.19.0 \|\| >=22.12.0 |
| Dependencies | 11 |
| Unpacked size | 27.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 87 |
| Author | Joel Kemp |
| Maintainers | pahen, mrjoelkemp, xhmikosr |
| Keywords | lookup, es6, amd, commonjs, sass, less, stylus, svelte, vue, partial, resolution, paths |

## Links

- npm: https://www.npmjs.com/package/filing-cabinet
- Repository: https://github.com/dependents/node-filing-cabinet
- Issues: https://github.com/dependents/node-filing-cabinet/issues
- npm.io page: https://npm.io/package/filing-cabinet

## Dependencies (11)

- [resolve](https://npm.io/package/resolve.md) ^1.22.12
- [commander](https://npm.io/package/commander.md) ^14.0.3
- [typescript](https://npm.io/package/typescript.md) ^6.0.3
- [sass-lookup](https://npm.io/package/sass-lookup.md) ^7.0.0
- [stylus-lookup](https://npm.io/package/stylus-lookup.md) ^7.0.0
- [tsconfig-paths](https://npm.io/package/tsconfig-paths.md) ^4.2.0
- [app-module-path](https://npm.io/package/app-module-path.md) ^2.2.0
- [enhanced-resolve](https://npm.io/package/enhanced-resolve.md) ^5.21.5
- [module-definition](https://npm.io/package/module-definition.md) ^7.0.0
- [module-lookup-amd](https://npm.io/package/module-lookup-amd.md) ^10.0.0
- [resolve-dependency-path](https://npm.io/package/resolve-dependency-path.md) ^5.0.0

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 6.0.0 (latest) — 2026-05-19
- 5.5.1 — 2026-05-09
- 5.5.0 — 2026-05-09
- 5.4.2 — 2026-05-05
- 5.4.1 — 2026-04-27
- 5.4.0 — 2026-04-26
- 5.3.0 — 2026-04-15
- 5.2.1 — 2026-04-14
- 5.2.0 — 2026-02-28
- 5.1.0 — 2026-02-09
- 5.0.3 — 2025-02-01
- 5.0.2 — 2024-04-24
- 5.0.1 — 2024-04-10
- 5.0.0 — 2024-04-10
- 4.2.0 — 2024-04-10
- … 72 more at https://npm.io/package/filing-cabinet/versions

## README

# filing-cabinet

[![CI](https://img.shields.io/github/actions/workflow/status/dependents/node-filing-cabinet/ci.yml?branch=main&label=CI&logo=github)](https://github.com/dependents/node-filing-cabinet/actions/workflows/ci.yml?query=branch%3Amain)
[![npm version](https://img.shields.io/npm/v/filing-cabinet?logo=npm&logoColor=fff)](https://www.npmjs.com/package/filing-cabinet)
[![npm downloads](https://img.shields.io/npm/dm/filing-cabinet)](https://www.npmjs.com/package/filing-cabinet)

> Get the file associated with a dependency/partial's path

## Installation

```sh
npm install filing-cabinet
```

## Quick Start

### ESM

```js
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import cabinet from 'filing-cabinet';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const result = cabinet({
  // import Button from './button'
  partial: './button',
  filename: path.join(__dirname, 'src', 'app.js'),
  directory: __dirname
});
```

### CommonJS

```js
const { default: cabinet } = require('filing-cabinet');
```

### Options

```js
const result = cabinet({
  // import Button from './button'
  partial: './button',
  filename: path.join(__dirname, 'src', 'app.js'),
  directory: __dirname
});

if (result) {
  console.log(result); // -> /absolute/path/to/src/button.js
} else {
  console.error('Dependency could not be resolved');
}
```

## API

| Member | Type | Description |
| --- | --- | --- |
| `cabinet(options)` | `Function` | Resolve a dependency to an absolute path |
| `cabinet.register(extension, resolver)` | `Function` | Register a custom resolver for a file extension |
| `cabinet.unregister(extension)` | `Function` | Remove a registered resolver |
| `cabinet.getLookup(extension)` | `Function` | Get the resolver for a file extension |
| `cabinet.supportedFileExtensions` | `string[]` | All currently registered file extensions |

### `cabinet(options: CabinetOptions)`

Resolves a dependency string from the context of a file.

**Returns:** `string` - absolute path to the resolved file, or an empty string if it could not be resolved.

#### Options

| Option | Type | Required | Description |
| --- | --- | --- | --- |
| `partial` | `string` | **Yes** | Dependency path to resolve |
| `directory` | `string` | **Yes** | Project root path used for resolution |
| `filename` | `string` | **Yes** | Path to the file containing `partial` |
| `ast` | `Object` | No | Pre-parsed AST for `filename` (avoids reparsing in JS module type detection) |
| `config` | `string \| Object` | No | **JS only.** RequireJS config (path or object) for AMD resolution |
| `configPath` | `string` | No | **JS only.** Path to the RequireJS config file when `config` is an object |
| `webpackConfig` | `string` | No | **JS only.** Webpack config path for webpack-style resolution; if the config exports an array, the first config is used |
| `nodeModulesConfig` | `Object \| Function` | No | Controls package entry selection when resolving from `node_modules` (see examples below) |
| `nodeModulesConfig.entry` | `string` | No | Object form: field name to prefer instead of `main` (for example `module`) |
| `nodeModulesConfig` (function) | `Function` | No | Function form: custom [`resolve` packageFilter](https://github.com/browserify/resolve#resolveid-opts-cb) callback for full control of package entry selection |
| `tsConfig` | `string \| Object` | No | **TS only.** TypeScript config path or pre-parsed config object |
| `tsConfigPath` | `string` | No | **TS only.** (Virtual) path to tsconfig when `tsConfig` is an object; needed for [Path Mapping](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping) |
| `noTypeDefinitions` | `boolean` | No | **TS only.** Prefer `*.js` over `*.d.ts` when resolving TypeScript dependencies |
| `fileSystem` | `Object` | No | An alternative `fs` implementation to use for reading `tsConfigPath` |

#### `nodeModulesConfig` examples

Object form - use a specific `package.json` field instead of `main`:

```js
cabinet({
  partial: 'some-package',
  filename: '/path/to/file.js',
  directory: '/path/to',
  nodeModulesConfig: { entry: 'module' }
});
```

Function form - full control via a custom `packageFilter`:

```js
cabinet({
  partial: 'some-package',
  filename: '/path/to/file.js',
  directory: '/path/to',
  nodeModulesConfig: (pkg) => {
    // prefer "module", fall back to "main"
    pkg.main = pkg.module ?? pkg.main;
    return pkg;
  }
});
```

### `cabinet.register(extension: string, resolver: (options: Object) => string)`

Register a custom resolver for a file extension.

**Parameters:**

* `extension` (`string`, required) - file extension to handle (for example `.py`, `.php`)
* `resolver` (`(options: Object) => string`, required) - function that receives the same `options` object passed to `cabinet(options)` and returns a resolved absolute path or an empty string

**Returns:** `void`

```js
cabinet.register('.py', (options) => {
  // resolve options.partial relative to options.filename
  return '/resolved/path/to/file.py';
});
```

For examples of resolver implementations, take a look at the built-in resolvers:

* [sass-lookup](https://github.com/dependents/node-sass-lookup)
* [stylus-lookup](https://github.com/dependents/node-stylus-lookup)
* [module-lookup-amd](https://github.com/dependents/node-module-lookup-amd)

If no resolver is registered for an extension, filing-cabinet falls back to a generic file resolver with extension defaulting behavior.

### `cabinet.unregister(extension: string)`

Remove the resolver registered for `extension`.

**Parameters:**

* `extension` (`string`, required) - file extension whose resolver should be removed

**Returns:** `void`

```js
cabinet.unregister('.py');
```

### `cabinet.getLookup(extension: string)`

Return the resolver function registered for `extension`, or `undefined` if none is registered.

**Parameters:**

* `extension` (`string`, required) - file extension to look up

**Returns:** `Function | undefined`

```js
const resolver = cabinet.getLookup('.ts'); // built-in TypeScript resolver
```

### `cabinet.supportedFileExtensions`

A `string[]` of all currently registered file extensions. Updated automatically by `register()` and `unregister()`.

```js
console.log(cabinet.supportedFileExtensions);
// ['.js', '.jsx', '.less', '.sass', '.scss', '.styl', '.svelte', '.ts', '.tsx', '.vue']
```

## Supported Languages

By default, filing-cabinet supports:

* JavaScript (CommonJS, AMD, ES6)
* TypeScript
* Sass (`.scss`, `.sass`), Less (`.less`), and Stylus (`.styl`)
* Svelte
* Vue

## Package `#imports` Field

filing-cabinet automatically resolves [Node.js package `imports`](https://nodejs.org/api/packages.html#subpath-imports) (dependencies starting with `#`) for both JavaScript and TypeScript files.

## CLI

Install globally:

```sh
npm install -g filing-cabinet
```

Run:

```sh
filing-cabinet [options] <path>
```

Run `filing-cabinet --help` for full usage.

## License

[MIT](LICENSE)

---
_Source: https://npm.io/package/filing-cabinet · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._