{"id":13526906,"url":"https://github.com/isaacs/node-mkdirp","last_synced_at":"2025-04-01T08:30:32.719Z","repository":{"id":1794308,"uuid":"2718248","full_name":"isaacs/node-mkdirp","owner":"isaacs","description":"Recursively mkdir, like `mkdir -p`, but in node.js","archived":false,"fork":true,"pushed_at":"2023-09-15T19:59:26.000Z","size":337,"stargazers_count":191,"open_issues_count":1,"forks_count":40,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-21T21:04:35.142Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"dominictarr/node-mkdirp","license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/isaacs.png","metadata":{"files":{"readme":"readme.markdown","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null},"funding":{"github":["isaacs","substack"]}},"created_at":"2011-11-06T01:33:28.000Z","updated_at":"2025-03-16T21:12:15.000Z","dependencies_parsed_at":"2023-02-10T12:15:56.921Z","dependency_job_id":"e75b98df-7078-4e5a-a567-56dffe6c064d","html_url":"https://github.com/isaacs/node-mkdirp","commit_stats":{"total_commits":139,"total_committers":12,"mean_commits":"11.583333333333334","dds":0.525179856115108,"last_synced_commit":"a2d14cfc56eaca96722057c2fed96b84868b3a24"},"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isaacs%2Fnode-mkdirp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isaacs%2Fnode-mkdirp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isaacs%2Fnode-mkdirp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isaacs%2Fnode-mkdirp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/isaacs","download_url":"https://codeload.github.com/isaacs/node-mkdirp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245028533,"owners_count":20549535,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T06:01:37.215Z","updated_at":"2025-04-01T08:30:32.348Z","avatar_url":"https://github.com/isaacs.png","language":"TypeScript","readme":"# mkdirp\n\nLike `mkdir -p`, but in Node.js!\n\nNow with a modern API and no\\* bugs!\n\n\u003csmall\u003e\\* may contain some bugs\u003c/small\u003e\n\n# example\n\n## pow.js\n\n```js\n// hybrid module, import or require() both work\nimport { mkdirp } from 'mkdirp'\n// or:\nconst { mkdirp } = require('mkdirp')\n\n// return value is a Promise resolving to the first directory created\nmkdirp('/tmp/foo/bar/baz').then(made =\u003e\n  console.log(`made directories, starting with ${made}`)\n)\n```\n\nOutput (where `/tmp/foo` already exists)\n\n```\nmade directories, starting with /tmp/foo/bar\n```\n\nOr, if you don't have time to wait around for promises:\n\n```js\nimport { mkdirp } from 'mkdirp'\n\n// return value is the first directory created\nconst made = mkdirp.sync('/tmp/foo/bar/baz')\nconsole.log(`made directories, starting with ${made}`)\n```\n\nAnd now /tmp/foo/bar/baz exists, huzzah!\n\n# methods\n\n```js\nimport { mkdirp } from 'mkdirp'\n```\n\n## `mkdirp(dir: string, opts?: MkdirpOptions) =\u003e Promise\u003cstring | undefined\u003e`\n\nCreate a new directory and any necessary subdirectories at `dir`\nwith octal permission string `opts.mode`. If `opts` is a string\nor number, it will be treated as the `opts.mode`.\n\nIf `opts.mode` isn't specified, it defaults to `0o777`.\n\nPromise resolves to first directory `made` that had to be\ncreated, or `undefined` if everything already exists. Promise\nrejects if any errors are encountered. Note that, in the case of\npromise rejection, some directories _may_ have been created, as\nrecursive directory creation is not an atomic operation.\n\nYou can optionally pass in an alternate `fs` implementation by\npassing in `opts.fs`. Your implementation should have\n`opts.fs.mkdir(path, opts, cb)` and `opts.fs.stat(path, cb)`.\n\nYou can also override just one or the other of `mkdir` and `stat`\nby passing in `opts.stat` or `opts.mkdir`, or providing an `fs`\noption that only overrides one of these.\n\n## `mkdirp.sync(dir: string, opts: MkdirpOptions) =\u003e string|undefined`\n\nSynchronously create a new directory and any necessary\nsubdirectories at `dir` with octal permission string `opts.mode`.\nIf `opts` is a string or number, it will be treated as the\n`opts.mode`.\n\nIf `opts.mode` isn't specified, it defaults to `0o777`.\n\nReturns the first directory that had to be created, or undefined\nif everything already exists.\n\nYou can optionally pass in an alternate `fs` implementation by\npassing in `opts.fs`. Your implementation should have\n`opts.fs.mkdirSync(path, mode)` and `opts.fs.statSync(path)`.\n\nYou can also override just one or the other of `mkdirSync` and\n`statSync` by passing in `opts.statSync` or `opts.mkdirSync`, or\nproviding an `fs` option that only overrides one of these.\n\n## `mkdirp.manual`, `mkdirp.manualSync`\n\nUse the manual implementation (not the native one). This is the\ndefault when the native implementation is not available or the\nstat/mkdir implementation is overridden.\n\n## `mkdirp.native`, `mkdirp.nativeSync`\n\nUse the native implementation (not the manual one). This is the\ndefault when the native implementation is available and\nstat/mkdir are not overridden.\n\n# implementation\n\nOn Node.js v10.12.0 and above, use the native `fs.mkdir(p,\n{recursive:true})` option, unless `fs.mkdir`/`fs.mkdirSync` has\nbeen overridden by an option.\n\n## native implementation\n\n- If the path is a root directory, then pass it to the underlying\n  implementation and return the result/error. (In this case,\n  it'll either succeed or fail, but we aren't actually creating\n  any dirs.)\n- Walk up the path statting each directory, to find the first\n  path that will be created, `made`.\n- Call `fs.mkdir(path, { recursive: true })` (or `fs.mkdirSync`)\n- If error, raise it to the caller.\n- Return `made`.\n\n## manual implementation\n\n- Call underlying `fs.mkdir` implementation, with `recursive:\nfalse`\n- If error:\n  - If path is a root directory, raise to the caller and do not\n    handle it\n  - If ENOENT, mkdirp parent dir, store result as `made`\n  - stat(path)\n    - If error, raise original `mkdir` error\n    - If directory, return `made`\n    - Else, raise original `mkdir` error\n- else\n  - return `undefined` if a root dir, or `made` if set, or `path`\n\n## windows vs unix caveat\n\nOn Windows file systems, attempts to create a root directory (ie,\na drive letter or root UNC path) will fail. If the root\ndirectory exists, then it will fail with `EPERM`. If the root\ndirectory does not exist, then it will fail with `ENOENT`.\n\nOn posix file systems, attempts to create a root directory (in\nrecursive mode) will succeed silently, as it is treated like just\nanother directory that already exists. (In non-recursive mode,\nof course, it fails with `EEXIST`.)\n\nIn order to preserve this system-specific behavior (and because\nit's not as if we can create the parent of a root directory\nanyway), attempts to create a root directory are passed directly\nto the `fs` implementation, and any errors encountered are not\nhandled.\n\n## native error caveat\n\nThe native implementation (as of at least Node.js v13.4.0) does\nnot provide appropriate errors in some cases (see\n[nodejs/node#31481](https://github.com/nodejs/node/issues/31481)\nand\n[nodejs/node#28015](https://github.com/nodejs/node/issues/28015)).\n\nIn order to work around this issue, the native implementation\nwill fall back to the manual implementation if an `ENOENT` error\nis encountered.\n\n# choosing a recursive mkdir implementation\n\nThere are a few to choose from! Use the one that suits your\nneeds best :D\n\n## use `fs.mkdir(path, {recursive: true}, cb)` if:\n\n- You wish to optimize performance even at the expense of other\n  factors.\n- You don't need to know the first dir created.\n- You are ok with getting `ENOENT` as the error when some other\n  problem is the actual cause.\n- You can limit your platforms to Node.js v10.12 and above.\n- You're ok with using callbacks instead of promises.\n- You don't need/want a CLI.\n- You don't need to override the `fs` methods in use.\n\n## use this module (mkdirp 1.x or 2.x) if:\n\n- You need to know the first directory that was created.\n- You wish to use the native implementation if available, but\n  fall back when it's not.\n- You prefer promise-returning APIs to callback-taking APIs.\n- You want more useful error messages than the native recursive\n  mkdir provides (at least as of Node.js v13.4), and are ok with\n  re-trying on `ENOENT` to achieve this.\n- You need (or at least, are ok with) a CLI.\n- You need to override the `fs` methods in use.\n\n## use [`make-dir`](http://npm.im/make-dir) if:\n\n- You do not need to know the first dir created (and wish to save\n  a few `stat` calls when using the native implementation for\n  this reason).\n- You wish to use the native implementation if available, but\n  fall back when it's not.\n- You prefer promise-returning APIs to callback-taking APIs.\n- You are ok with occasionally getting `ENOENT` errors for\n  failures that are actually related to something other than a\n  missing file system entry.\n- You don't need/want a CLI.\n- You need to override the `fs` methods in use.\n\n## use mkdirp 0.x if:\n\n- You need to know the first directory that was created.\n- You need (or at least, are ok with) a CLI.\n- You need to override the `fs` methods in use.\n- You're ok with using callbacks instead of promises.\n- You are not running on Windows, where the root-level ENOENT\n  errors can lead to infinite regress.\n- You think vinyl just sounds warmer and richer for some weird\n  reason.\n- You are supporting truly ancient Node.js versions, before even\n  the advent of a `Promise` language primitive. (Please don't.\n  You deserve better.)\n\n# cli\n\nThis package also ships with a `mkdirp` command.\n\n```\n$ mkdirp -h\n\nusage: mkdirp [DIR1,DIR2..] {OPTIONS}\n\n  Create each supplied directory including any necessary parent directories\n  that don't yet exist.\n\n  If the directory already exists, do nothing.\n\nOPTIONS are:\n\n  -m\u003cmode\u003e       If a directory needs to be created, set the mode as an octal\n  --mode=\u003cmode\u003e  permission string.\n\n  -v --version   Print the mkdirp version number\n\n  -h --help      Print this helpful banner\n\n  -p --print     Print the first directories created for each path provided\n\n  --manual       Use manual implementation, even if native is available\n```\n\n# install\n\nWith [npm](http://npmjs.org) do:\n\n```\nnpm install mkdirp\n```\n\nto get the library locally, or\n\n```\nnpm install -g mkdirp\n```\n\nto get the command everywhere, or\n\n```\nnpx mkdirp ...\n```\n\nto run the command without installing it globally.\n\n# platform support\n\nThis module works on node v8, but only v10 and above are officially\nsupported, as Node v8 reached its LTS end of life 2020-01-01, which is in\nthe past, as of this writing.\n\n# license\n\nMIT\n","funding_links":["https://github.com/sponsors/isaacs","https://github.com/sponsors/substack"],"categories":["Repository","JavaScript","Uncategorized"],"sub_categories":["Filesystem","Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisaacs%2Fnode-mkdirp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fisaacs%2Fnode-mkdirp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisaacs%2Fnode-mkdirp/lists"}