mkdirp

https://www.npmjs.com/package/mkdirp
Admin
mkdirp is a Node.js utility that recursively creates directories like the Unix mkdir -p command,...
Tokens:9,399
Snippets:104
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install via npm

Source: https://www.npmjs.com/package/mkdirp?activeTab=code

Quick installation command for the package.

```bash
npm i mkdirp
```

--------------------------------

### Install mkdirp with npm

Source: https://www.npmjs.com/package/mkdirp?activeTab=dependents

Shows how to install the mkdirp package using npm, both locally for a project and globally for command-line access.

```bash
npm install mkdirp

```

```bash
npm install -g mkdirp

```

```bash
npx mkdirp ...

```

--------------------------------

### Install mkdirp

Source: https://www.npmjs.com/package/mkdirp?activeTab=code

Commands for installing the mkdirp package locally, globally, or running it via npx.

```bash
npm install mkdirp
```

```bash
npm install -g mkdirp
```

```bash
npx mkdirp ...
```

--------------------------------

### Install mkdirp Globally

Source: https://www.npmjs.com/package/mkdirp?activeTab=readme

Installs the mkdirp command-line tool globally on the system using npm, making it accessible from any directory.

```bash
npm install -g mkdirp

```

--------------------------------

### Run mkdirp with npx

Source: https://www.npmjs.com/package/mkdirp?activeTab=readme

Executes the mkdirp command without a global installation by using npx.

```bash
npx mkdirp ...

```

--------------------------------

### Install mkdirp Package

Source: https://www.npmjs.com/package/mkdirp?activeTab=readme

Installs the mkdirp package using npm, as shown in the package sidebar.

```bash
npm i mkdirp

```

--------------------------------

### Install mkdirp Locally

Source: https://www.npmjs.com/package/mkdirp?activeTab=readme

Installs the mkdirp package locally within a project using npm.

```bash
npm install mkdirp

```

--------------------------------

### mkdirp.sync(dir, opts)

Source: https://www.npmjs.com/package/mkdirp?activeTab=readme

Synchronously create a new directory and any necessary subdirectories.

```APIDOC
## mkdirp.sync(dir, opts)

### Description
Synchronously create a new directory and any necessary subdirectories at `dir` with octal permission string `opts.mode`.

### Parameters
#### Path Parameters
- **dir** (string) - Required - The path to the directory to create.

#### Request Body
- **opts** (MkdirpOptions) - Required - Configuration object. Can include `mode` (octal permission string, defaults to 0o777), `fs` (alternate fs implementation), `mkdirSync`, or `statSync` overrides.

### Response
#### Success Response (200)
- **string | undefined** - Returns the first directory created, or undefined if everything already exists.

### Request Example
```javascript
import { mkdirp } from 'mkdirp';
const made = mkdirp.sync('/tmp/foo/bar/baz');
```
```

--------------------------------

### mkdirp - Basic Usage

Source: https://www.npmjs.com/package/mkdirp?activeTab=dependencies

Demonstrates how to use the mkdirp function to create directories recursively using Promises.

```APIDOC
## Basic Usage with Promises

### Description
Creates new directories and any necessary subdirectories recursively. The function returns a Promise that resolves to the first directory that had to be created, or `undefined` if all directories already existed.

### Method
`mkdirp(dir: string, opts?: MkdirpOptions) => Promise<string | undefined>`

### Endpoint
N/A (Node.js module function)

### Parameters
#### Path Parameters
- **dir** (string) - Required - The path of the directory to create.

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
// hybrid module, import or require() both work
import { mkdirp } from 'mkdirp'
// or:
const { mkdirp } = require('mkdirp')

// return value is a Promise resolving to the first directory created
mkdirp('/tmp/foo/bar/baz').then(made =>
  console.log(`made directories, starting with ${made}`)
)
```

### Response
#### Success Response (Promise resolves)
- **made** (string | undefined) - The first directory that had to be created, or `undefined` if all directories already existed.

#### Response Example
```
made directories, starting with /tmp/foo/bar
```

### Error Handling
Promise rejects if any errors are encountered during directory creation. Note that some directories may have been created before rejection.
```

--------------------------------

### mkdirp(dir, opts)

Source: https://www.npmjs.com/package/mkdirp?activeTab=readme

Asynchronously create a new directory and any necessary subdirectories.

```APIDOC
## mkdirp(dir, opts)

### Description
Create a new directory and any necessary subdirectories at `dir` with octal permission string `opts.mode`.

### Parameters
#### Path Parameters
- **dir** (string) - Required - The path to the directory to create.

#### Request Body
- **opts** (MkdirpOptions) - Optional - Configuration object. Can include `mode` (octal permission string, defaults to 0o777), `fs` (alternate fs implementation), `mkdir`, or `stat` overrides.

### Response
#### Success Response (200)
- **Promise<string | undefined>** - Resolves to the first directory created, or undefined if everything already exists.

### Request Example
```javascript
import { mkdirp } from 'mkdirp';
mkdirp('/tmp/foo/bar/baz').then(made => console.log(made));
```
```

--------------------------------

### mkdirp - Options and Customization

Source: https://www.npmjs.com/package/mkdirp?activeTab=dependencies

Explains how to use options like `mode` and custom `fs` implementations with mkdirp.

```APIDOC
## Options and Customization

### Description
Details on how to customize the behavior of `mkdirp` using options such as `mode` for permissions and providing custom `fs` implementations.

### Parameters
#### `opts.mode`
- **Type**: `string` or `number` (octal permission string)
- **Description**: Sets the octal permission for the created directories. Defaults to `0o777` if not specified.

#### `opts.fs`
- **Type**: `object`
- **Description**: Allows providing a custom file system implementation. The implementation must have `mkdir(path, opts, cb)` and `stat(path, cb)` methods for the asynchronous version, or `mkdirSync(path, mode)` and `statSync(path)` for the synchronous version.

#### Overriding Specific `fs` Methods
- **`opts.stat`**: Override only the `stat` method.
- **`opts.mkdir`**: Override only the `mkdir` method.
- **`opts.statSync`**: Override only the `statSync` method.
- **`opts.mkdirSync`**: Override only the `mkdirSync` method.

### Implementation Details
- **Native Implementation**: Uses Node.js v10.12.0+ `fs.mkdir(p, {recursive:true})` if available and `fs` methods are not overridden.
- **Manual Implementation**: Used when the native implementation is not available or `fs` methods are overridden. It recursively calls the underlying `fs.mkdir` with `recursive: false`.

### Caveats
- **Windows vs. Unix**: Behavior for creating root directories differs. On Windows, attempts to create a root directory will fail. On POSIX systems, they succeed silently. `mkdirp` preserves this system-specific behavior by passing root directory creation directly to the `fs` implementation.
```

--------------------------------

### mkdirp - Synchronous Usage

Source: https://www.npmjs.com/package/mkdirp?activeTab=dependencies

Demonstrates how to use the synchronous version of mkdirp to create directories recursively.

```APIDOC
## Synchronous Usage

### Description
Synchronously creates a new directory and any necessary subdirectories. The function returns the first directory that had to be created, or `undefined` if all directories already existed.

### Method
`mkdirp.sync(dir: string, opts: MkdirpOptions) => string | undefined`

### Endpoint
N/A (Node.js module function)

### Parameters
#### Path Parameters
- **dir** (string) - Required - The path of the directory to create.

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { mkdirp } from 'mkdirp'

// return value is the first directory created
const made = mkdirp.sync('/tmp/foo/bar/baz')
console.log(`made directories, starting with ${made}`)
```

### Response
#### Success Response
- **made** (string | undefined) - The first directory that had to be created, or `undefined` if all directories already existed.

#### Response Example
```
made directories, starting with /tmp/foo/bar
```
```

--------------------------------

### mkdirp - Manual and Native Implementations

Source: https://www.npmjs.com/package/mkdirp?activeTab=dependencies

Explains the difference between the manual and native implementations of mkdirp.

```APIDOC
## Manual vs. Native Implementations

### Description
This section clarifies the two primary implementation strategies used by `mkdirp`: the native Node.js implementation and the manual fallback implementation.

### `mkdirp.manual` and `mkdirp.manualSync`
- **Description**: These functions explicitly use the manual implementation strategy. This strategy is employed by default when the native Node.js `fs.mkdir` with the `recursive: true` option is unavailable or when custom `fs.stat` or `fs.mkdir` implementations are provided.

### `mkdirp.native` and `mkdirp.nativeSync`
- **Description**: These functions explicitly use the native Node.js implementation. This is the default behavior when the native `fs.mkdir` with `recursive: true` is available and no custom `fs` methods are overridden.
```

--------------------------------

### mkdirp - Asynchronous Directory Creation

Source: https://www.npmjs.com/package/mkdirp?activeTab=dependents

Demonstrates how to use the asynchronous `mkdirp` function to create directories recursively. It returns a Promise that resolves to the first directory that had to be created, or undefined if all directories already existed. Rejects on error.

```APIDOC
## mkdirp(dir: string, opts?: MkdirpOptions) => Promise<string | undefined>

### Description
Create a new directory and any necessary subdirectories at `dir` with octal permission string `opts.mode`. If `opts` is a string or number, it will be treated as the `opts.mode`. If `opts.mode` isn't specified, it defaults to `0o777`.

Promise resolves to first directory `made` that had to be created, or `undefined` if everything already exists. Promise rejects if any errors are encountered. Note that, in the case of promise rejection, some directories _may_ have been created, as recursive directory creation is not an atomic operation.

You can optionally pass in an alternate `fs` implementation by passing in `opts.fs`. Your implementation should have `opts.fs.mkdir(path, opts, cb)` and `opts.fs.stat(path, cb)`.
You can also override just one or the other of `mkdir` and `stat` by passing in `opts.stat` or `opts.mkdir`, or providing an `fs` option that only overrides one of these.

### Method
`mkdirp`

### Endpoint
N/A (Node.js module function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
// hybrid module, import or require() both work
import { mkdirp } from 'mkdirp'
// or:
const { mkdirp } = require('mkdirp')

// return value is a Promise resolving to the first directory created
mkdirp('/tmp/foo/bar/baz').then(made =>
  console.log(`made directories, starting with ${made}`)
)
```

### Response
#### Success Response (Promise resolves)
- **made** (string | undefined) - The first directory that had to be created, or `undefined` if all directories already existed.

#### Response Example
```javascript
// Output (where /tmp/foo already exists)
// made directories, starting with /tmp/foo/bar
```
```

--------------------------------

### View CLI Help

Source: https://www.npmjs.com/package/mkdirp?activeTab=code

Displays the help banner for the mkdirp command-line interface.

```bash
$ mkdirp -h

usage: mkdirp [DIR1,DIR2..] {OPTIONS}

  Create each supplied directory including any necessary parent directories
  that don't yet exist.

  If the directory already exists, do nothing.

OPTIONS are:

  -m<mode>       If a directory needs to be created, set the mode as an octal
  --mode=<mode>  permission string.

  -v --version   Print the mkdirp version number

  -h --help      Print this helpful banner

  -p --print     Print the first directories created for each path provided

  --manual       Use manual implementation, even if native is available
```

--------------------------------

### mkdirp.manual and mkdirp.manualSync

Source: https://www.npmjs.com/package/mkdirp?activeTab=code

These methods explicitly use the manual implementation of mkdirp, which is used as a fallback or when the `fs` options are overridden.

```APIDOC
## mkdirp.manual, mkdirp.manualSync

### Description
Use the manual implementation (not the native one). This is the default when the native implementation is not available or the stat/mkdir implementation is overridden.

### Usage
These are typically used internally or when explicitly wanting to ensure the manual implementation is used.

### Example
```javascript
import { mkdirp } from 'mkdirp'

// Explicitly use manual implementation
mkdirp.manual('/tmp/some/path')
mkdirp.manualSync('/tmp/some/path')
```
```

--------------------------------

### mkdirp CLI Help

Source: https://www.npmjs.com/package/mkdirp?activeTab=readme

Displays the help message for the mkdirp command-line interface, outlining available options for directory creation.

```bash
$ mkdirp -h

usage: mkdirp [DIR1,DIR2..] {OPTIONS}

  Create each supplied directory including any necessary parent directories
  that don't yet exist.

  If the directory already exists, do nothing.

OPTIONS are:

  -m<mode>       If a directory needs to be created, set the mode as an octal
  --mode=<mode>  permission string.

  -v --version   Print the mkdirp version number

  -h --help      Print this helpful banner

  -p --print     Print the first directories created for each path provided

  --manual       Use manual implementation, even if native is available

```

--------------------------------

### Create Directories Asynchronously

Source: https://www.npmjs.com/package/mkdirp?activeTab=readme

Use this function to create directories recursively. It returns a Promise that resolves to the first directory that had to be created. Ensure 'mkdirp' is imported.

```javascript
import { mkdirp } from 'mkdirp'
// or:
const { mkdirp } = require('mkdirp')

// return value is a Promise resolving to the first directory created
mkdirp('/tmp/foo/bar/baz').then(made =>
  console.log(`made directories, starting with ${made}`)
)
```

--------------------------------

### mkdirp.native and mkdirp.manual

Source: https://www.npmjs.com/package/mkdirp

Exposes the native and manual implementations of mkdirp, allowing for explicit control over which implementation to use.

```APIDOC
## `mkdirp.manual`, `mkdirp.manualSync`

### Description
Use the manual implementation (not the native one). This is the default when the native implementation is not available or the stat/mkdir implementation is overridden.

## `mkdirp.native`, `mkdirp.nativeSync`

### Description
Use the native implementation (not the manual one). This is the default when the native implementation is available and stat/mkdir are not overridden.
```

--------------------------------

### mkdirp - Asynchronous Directory Creation

Source: https://www.npmjs.com/package/mkdirp

Creates a directory and any necessary subdirectories asynchronously. It returns a Promise that resolves to the first directory that had to be created, or undefined if all directories already existed. Rejects on error.

```APIDOC
## mkdirp(dir: string, opts?: MkdirpOptions) => Promise<string | undefined>

### Description
Create a new directory and any necessary subdirectories at `dir` with octal permission string `opts.mode`. If `opts` is a string or number, it will be treated as the `opts.mode`. If `opts.mode` isn't specified, it defaults to `0o777`.

Promise resolves to first directory `made` that had to be created, or `undefined` if everything already exists. Promise rejects if any errors are encountered. Note that, in the case of promise rejection, some directories _may_ have been created, as recursive directory creation is not an atomic operation.

You can optionally pass in an alternate `fs` implementation by passing in `opts.fs`. Your implementation should have `opts.fs.mkdir(path, opts, cb)` and `opts.fs.stat(path, cb)`. You can also override just one or the other of `mkdir` and `stat` by passing in `opts.stat` or `opts.mkdir`, or providing an `fs` option that only overrides one of these.

### Parameters
#### Path Parameters
- **dir** (string) - Required - The directory path to create.
- **opts** (MkdirpOptions) - Optional - Options for directory creation.
  - **mode** (string | number) - Optional - Octal permission string for the directories. Defaults to `0o777`.
  - **fs** (object) - Optional - An alternate `fs` implementation with `mkdir` and `stat` methods.
    - **mkdir** (function) - Required if `fs` is provided - The mkdir function.
    - **stat** (function) - Required if `fs` is provided - The stat function.

### Request Example
```javascript
import { mkdirp } from 'mkdirp'

mkdirp('/tmp/foo/bar/baz').then(made =>
  console.log(`made directories, starting with ${made}`)
)
```

### Response
#### Success Response (200)
- **made** (string | undefined) - The first directory that had to be created, or `undefined` if all directories already existed.

#### Response Example
```json
"/tmp/foo/bar"
```
```

--------------------------------

### mkdirp - Asynchronous Directory Creation

Source: https://www.npmjs.com/package/mkdirp?activeTab=code

Creates a new directory and any necessary subdirectories asynchronously. It returns a Promise that resolves to the first directory created or undefined if all directories already exist. Rejects on error.

```APIDOC
## mkdirp(dir: string, opts?: MkdirpOptions) => Promise<string | undefined>

### Description
Create a new directory and any necessary subdirectories at `dir` with octal permission string `opts.mode`. If `opts` is a string or number, it will be treated as the `opts.mode`. If `opts.mode` isn't specified, it defaults to `0o777`.
Promise resolves to first directory `made` that had to be created, or `undefined` if everything already exists. Promise rejects if any errors are encountered.

### Parameters
#### Path Parameters
- **dir** (string) - Required - The directory path to create.
#### Query Parameters
- **opts** (MkdirpOptions) - Optional - Options for directory creation.
  - **mode** (string | number) - Optional - Octal permission string for the directories. Defaults to `0o777`.
  - **fs** (object) - Optional - An alternate `fs` implementation with `mkdir` and `stat` methods.

### Request Example
```javascript
import { mkdirp } from 'mkdirp'

mkdirp('/tmp/foo/bar/baz').then(made =>
  console.log(`made directories, starting with ${made}`)
)
```

### Response
#### Success Response (200)
- **made** (string | undefined) - The first directory that had to be created, or `undefined` if all directories already existed.

#### Response Example
```json
"/tmp/foo/bar"
```
```

--------------------------------

### mkdirp.sync - Synchronous Directory Creation

Source: https://www.npmjs.com/package/mkdirp?activeTab=code

Synchronously creates a new directory and any necessary subdirectories. It returns the first directory created or undefined if all directories already exist.

```APIDOC
## mkdirp.sync(dir: string, opts: MkdirpOptions) => string|undefined

### Description
Synchronously create a new directory and any necessary subdirectories at `dir` with octal permission string `opts.mode`. If `opts` is a string or number, it will be treated as the `opts.mode`. If `opts.mode` isn't specified, it defaults to `0o777`.
Returns the first directory that had to be created, or undefined if everything already exists.

### Parameters
#### Path Parameters
- **dir** (string) - Required - The directory path to create.
#### Query Parameters
- **opts** (MkdirpOptions) - Required - Options for directory creation.
  - **mode** (string | number) - Optional - Octal permission string for the directories. Defaults to `0o777`.
  - **fs** (object) - Optional - An alternate `fs` implementation with `mkdirSync` and `statSync` methods.

### Request Example
```javascript
import { mkdirp } from 'mkdirp'

const made = mkdirp.sync('/tmp/foo/bar/baz')
console.log(`made directories, starting with ${made}`)
```

### Response
#### Success Response (200)
- **made** (string | undefined) - The first directory that had to be created, or `undefined` if all directories already existed.

#### Response Example
```json
"/tmp/foo/bar"
```
```

--------------------------------

### Create Directories Synchronously

Source: https://www.npmjs.com/package/mkdirp?activeTab=readme

Use this synchronous function to create directories recursively. It returns the first directory that had to be created. Ensure 'mkdirp' is imported.

```javascript
import { mkdirp } from 'mkdirp'

// return value is the first directory created
const made = mkdirp.sync('/tmp/foo/bar/baz')
console.log(`made directories, starting with ${made}`)
```

--------------------------------

### mkdirp CLI Usage

Source: https://www.npmjs.com/package/mkdirp

Displays the help message for the mkdirp command-line interface, outlining available options for creating directories recursively.

```bash
mkdirp -h

usage: mkdirp [DIR1,DIR2..] {OPTIONS}

  Create each supplied directory including any necessary parent directories
  that don't yet exist.

  If the directory already exists, do nothing.

OPTIONS are:

  -m<mode>       If a directory needs to be created, set the mode as an octal
  --mode=<mode>  permission string.

  -v --version   Print the mkdirp version number

  -h --help      Print this helpful banner

  -p --print     Print the first directories created for each path provided

  --manual       Use manual implementation, even if native is available

```

--------------------------------

### mkdirp Implementation Details

Source: https://www.npmjs.com/package/mkdirp?activeTab=dependents

Details on the native and manual implementations of mkdirp, including how it handles different Node.js versions and platform-specific behaviors.

```APIDOC
## Implementation Details

### Native Implementation
On Node.js v10.12.0 and above, `mkdirp` uses the native `fs.mkdir(p, {recursive:true})` option, unless `fs.mkdir`/`fs.mkdirSync` has been overridden by an option.

- If the path is a root directory, then pass it to the underlying implementation and return the result/error. (In this case, it'll either succeed or fail, but we aren't actually creating any dirs.)
- Walk up the path statting each directory, to find the first path that will be created, `made`.
- Call `fs.mkdir(path, { recursive: true })` (or `fs.mkdirSync`)
- If error, raise it to the caller.
- Return `made`.

### Manual Implementation
- Call underlying `fs.mkdir` implementation, with `recursive: false`
- If error:
  - If path is a root directory, raise to the caller and do not handle it
  - If ENOENT, mkdirp parent dir, store result as `made`
  - stat(path)
    - If error, raise original `mkdir` error
    - If directory, return `made`
    - Else, raise original `mkdir` error
- else
  - return `undefined` if a root dir, or `made` if set, or `path`

### `mkdirp.manual`, `mkdirp.manualSync`
Use the manual implementation (not the native one). This is the default when the native implementation is not available or the stat/mkdir implementation is overridden.

### `mkdirp.native`, `mkdirp.nativeSync`
Use the native implementation (not the manual one). This is the default when the native implementation is available and stat/mkdir are not overridden.

### Windows vs Unix Caveat
On Windows file systems, attempts to create a root directory (ie, a drive letter or root UNC path) will fail. If the root directory exists, then it will fail with `EPERM`. If the root directory does not exist, then it will fail with `ENOENT`.
On posix file systems, attempts to create a root directory (in recursive mode) will succeed silently, as it is treated like just another directory that already exists. (In non-recursive mode, of course, it fails with `EEXIST`.)
In order to preserve this system-specific behavior (and because it's not as if we can create the parent of a root directory anyway), attempts to create a root directory are passed directly to the `fs` implementation, and any errors encountered are not handled.
```

--------------------------------

### mkdirp.native and mkdirp.nativeSync

Source: https://www.npmjs.com/package/mkdirp?activeTab=code

These methods explicitly use the native Node.js `fs.mkdir` implementation, which is the default when available and not overridden.

```APIDOC
## mkdirp.native, mkdirp.nativeSync

### Description
Use the native implementation (not the manual one). This is the default when the native implementation is available and stat/mkdir are not overridden.

### Usage
These are typically used internally or when explicitly wanting to ensure the native implementation is used.

### Example
```javascript
import { mkdirp } from 'mkdirp'

// Explicitly use native implementation (if available)
mkdirp.native('/tmp/some/path')
mkdirp.nativeSync('/tmp/some/path')
```
```

--------------------------------

### Import mkdirp

Source: https://www.npmjs.com/package/mkdirp?activeTab=readme

This shows the basic import statement required to use the mkdirp functionality.

```javascript
import { mkdirp } from 'mkdirp'
```
Tokens:
Raw