# find-import

> Find and load first instance of js/json in parent directories.

Latest version **1.0.14** (published 2025-02-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install find-import
pnpm add find-import
yarn add find-import
bun add find-import
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 1.0.14 |
| Published | 2025-02-17 |
| First published | 2022-05-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=20 |
| Dependencies | 1 |
| Unpacked size | 7.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 9 |
| Author | JacobLey |
| Maintainers | jacobley |
| Keywords | first, parent, load |

## Links

- npm: https://www.npmjs.com/package/find-import
- Repository: https://github.com/JacobLey/leyman
- Homepage: https://github.com/JacobLey/leyman/tree/main/tools/find-import#readme
- Issues: https://github.com/JacobLey/leyman/issues
- npm.io page: https://npm.io/package/find-import

## Dependencies (1)

- [parse-cwd](https://npm.io/package/parse-cwd.md) ^1.1.2

## Recent versions

- 1.0.14 (latest) — 2025-02-17
- 1.0.6-dev.6bc00b97a3757a3c8a7e4c9fc6698d34d57625cc4b0ca38dfe72449cf98f9a24 (dev) — 2022-08-15
- 1.0.13 — 2025-01-05
- 1.0.12 — 2024-12-31
- 1.0.11 — 2024-11-01
- 1.0.10 — 2024-10-26
- 1.0.9 — 2024-10-23
- 1.0.8 — 2024-08-08
- 1.0.7 — 2024-08-04
- 1.0.6 — 2022-08-15
- 1.0.6-dev.1e6fb2eb001cea38d49407180d13e11c4ed1c25c — 2022-08-15
- 1.0.6-dev.6df2bca68be79d74dfcb9028c6ebc8f3a0dcbd24f796b1344d7f824d225d161a — 2022-08-14
- 1.0.6-dev.6d40ad53c428177f21d8b184fccd23db6500aa4c — 2022-08-14
- 1.0.5-dev.4db653f8e93ccd8fe38bba2de59602e19620b84382e3f19e68fd5c5fda40b1e3 — 2022-08-10
- 1.0.5-dev.6150c44a1e003315375046a34cb8cb25c1c54c47 — 2022-08-10
- … 22 more at https://npm.io/package/find-import/versions

## README

<div style="text-align:center">

# find-import
Find and load first instance of js/json in parent directories.

[![npm package](https://badge.fury.io/js/find-import.svg)](https://www.npmjs.com/package/find-import)
[![License](https://img.shields.io/npm/l/find-import.svg)](https://github.com/JacobLey/leyman/blob/main/tools/find-import/LICENSE)

</div>

## Contents
- [Introduction](#introduction)
- [Install](#install)
- [Example](#example)
- [Usage](#usage)
- [API](#api)
  - [findImport](#findimportfilenames-options)

## Introduction

Load the first instance of a found module.

Optionally specify depth preference to prefer "top-most" packages.

Supports `.json`, `.cjs`, `.mjs`, and `.js`.

Returns the path and contents of the found module.

## Install

```sh
npm i find-import
```

## Example

Given file structure
```
/
└─┬ root
  ├── my-file.cjs // module.exports = { abc: 123 }
  └─┬ my-package
    └── my-file.json // { "foo": "bar" }
```

```ts
// cwd = /root/my-package
import { findImport } from 'find-import';

let found;

found = await findImport(['my-file.cjs', 'my-file.json']);
found.content // { foo: 'bar' }
found.filePath // /root/my-package/my-file.json

found = await findImport(['my-file.cjs', 'my-file.json'], {
    direction: 'down',
});
found.content // { abc: 123 }
found.filePath // /root/my-file.cjs

found = await findImport(['my-file.cjs', 'my-file.json'], {
    direction: 'down',
    startAt: '/root/my-package',
});
found.filePath // /root/my-package/my-file.json


found = await findImport(['my-file.cjs', 'my-file.json'], {
    cwd: '/root',
});
found.filePath // /root/my-package/my-file.cjs
```

## Usage

`find-import` is an ESM module. That means it _must_ be `import`ed. To load from a CJS module, use dynamic import `const { findImport } = await import('find-import');`.

## API

### findImport(fileNames, options?)

Finds first instance of matching module, and loads. Returns file path to module and content.

Note that `content` is the result of a dynamic `import()` call. If accessing the default content, it may be necessary/convenient to extract that content. See [default-import](https://www.npmjs.com/package/default-import) for a potential solution.

### fileNames

string or array of strings

List of file names to search for in each directory.

#### options

- cwd
  - Type: `string` or `URL`
  - optional, defaults to `process.cwd()`
  - Directory to use as base directory.
  - See [`parse-cwd`](https://www.npmjs.com/package/parse-cwd).

- direction
  - `'up'`(default) or `'down'`
  - direction to search for files.
    - `'up'` indicates `/foo/bar` -> `/foo` -> `/`
    - `'down'` is opposite, `/` -> `/foo` -> `/foo/bar`

- startAt
  - Type: `string` or `URL`
  - optional, defaults to `/`
  - Top-most "root" directory to limit search.

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