How do I use package-directory to find the project root in async Node.js code?

Import the packageDirectory function and call it with optional options like cwd. For example, await packageDirectory({ cwd: './someDir' }) returns the root path or undefined if not found, as shown in the README usage.

package-directory vs find-up: which should I use for file searching?

Use package-directory specifically for locating the project root via package.json, while find-up is more general for finding any file by name. package-directory integrates with find-up but is optimized for this common task, reducing boilerplate code.

How can I ignore package.json files that only have a type field in ESM projects?

Set the ignoreTypeOnlyPackageJson option to true when calling the API. This treats such files as ESM scope markers instead of package roots, preventing incorrect detection in modern Node.js setups, as explained in the README.

Does package-directory work in monorepos with multiple package.json files?

It finds the nearest package.json from the starting directory, so in monorepos, it will only return the first valid root encountered. For multi-root detection, you might need to implement custom logic or use other tools.

What happens if there's no package.json in the directory tree?

The function returns undefined, so your code should handle this case. It's designed to fail gracefully, but you may need fallback mechanisms for projects without standard npm structure.

Can I start the search from a specific folder instead of the current working directory?

Yes, use the cwd option in the options object. For instance, packageDirectorySync({ cwd: '/path/to/start' }) will begin searching from that directory, as documented in the API section.

package-directory — Find Node.js Project Root

What is package-directory?

package-directory is a Node.js library that finds the root directory of a Node.js project or npm package by searching for a `package.json` file while walking up the directory tree. It solves the problem of tools needing to reliably locate the project context from any subdirectory, which is crucial for configuration, path resolution, and build automation.

Target Audience

Node.js developers and tool authors who need to programmatically determine the project root for scripts, CLIs, build tools, or development utilities.

Value Proposition

Developers choose package-directory for its simplicity, reliability, and seamless integration with the Node.js ecosystem. It provides both async and sync APIs with configurable options, making it a robust solution compared to manual directory traversal.

Find the root directory of a Node.js project or npm package

Use Cases

Best For

Building CLI tools that need to locate project configuration files
Writing build scripts that require the project root for path resolution
Developing IDE extensions or linters that operate within a project context
Creating development utilities that automate tasks based on project structure
Integrating with other file-finding libraries like `find-up` or `package-up`
Handling edge cases in monorepos or projects with ESM configuration

Not Ideal For

Projects that define root directories with files other than package.json (e.g., .git, composer.json for PHP)
Applications running in environments without file system access, like browser-based tools or serverless functions with restricted I/O
Monorepos where tools need to detect multiple package.json files without stopping at the first valid root
Teams requiring built-in caching for repeated directory lookups to avoid performance overhead

Pros & Cons

Pros

Accurate Root Detection

Reliably locates the project root by searching for package.json, with an option to ignore files containing only a type field, ensuring correct handling of ESM scopes as per the README.

Flexible API Design

Provides both Promise-based async (packageDirectory) and synchronous (packageDirectorySync) functions, making it adaptable to different Node.js coding styles and use cases.

Configurable Search Options

Allows setting a custom starting directory (cwd) and toggling ignoreTypeOnlyPackageJson, offering control over edge cases in modern project setups as documented in the API.

Ecosystem Integration

Designed to work seamlessly with related utilities like package-up and find-up, enhancing its utility in toolchains and build processes, as noted in the README's Related section.

Cons

Single File Dependency

Solely relies on package.json for detection, so it fails in projects without this file or those using alternative root markers, limiting its universality.

No Multi-Root Support

Stops at the first valid package.json encountered, making it unsuitable for tools that need to identify all package roots in nested monorepo structures.

Synchronous Performance Risk

The sync API can block the event loop when walking up deep directory trees, which may impact performance in I/O-heavy or real-time applications.

Frequently Asked Questions

What is package-directory?

Target Audience

Node.js developers and tool authors who need to programmatically determine the project root for scripts, CLIs, build tools, or development utilities.

Value Proposition

Use Cases

Best For

Building CLI tools that need to locate project configuration files
Writing build scripts that require the project root for path resolution
Developing IDE extensions or linters that operate within a project context
Creating development utilities that automate tasks based on project structure
Integrating with other file-finding libraries like `find-up` or `package-up`
Handling edge cases in monorepos or projects with ESM configuration

Not Ideal For

Projects that define root directories with files other than package.json (e.g., .git, composer.json for PHP)
Applications running in environments without file system access, like browser-based tools or serverless functions with restricted I/O
Monorepos where tools need to detect multiple package.json files without stopping at the first valid root
Teams requiring built-in caching for repeated directory lookups to avoid performance overhead

Pros & Cons

Pros

Accurate Root Detection

Reliably locates the project root by searching for package.json, with an option to ignore files containing only a type field, ensuring correct handling of ESM scopes as per the README.

Flexible API Design

Provides both Promise-based async (packageDirectory) and synchronous (packageDirectorySync) functions, making it adaptable to different Node.js coding styles and use cases.

Configurable Search Options

Allows setting a custom starting directory (cwd) and toggling ignoreTypeOnlyPackageJson, offering control over edge cases in modern project setups as documented in the API.

Ecosystem Integration

Designed to work seamlessly with related utilities like package-up and find-up, enhancing its utility in toolchains and build processes, as noted in the README's Related section.

Cons

Single File Dependency

Solely relies on package.json for detection, so it fails in projects without this file or those using alternative root markers, limiting its universality.

No Multi-Root Support

Stops at the first valid package.json encountered, making it unsuitable for tools that need to identify all package roots in nested monorepo structures.

Synchronous Performance Risk

The sync API can block the event loop when walking up deep directory trees, which may impact performance in I/O-heavy or real-time applications.

Frequently Asked Questions

package-directory

What is package-directory?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

package-directory

What is package-directory?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?