# symlink-dir

> Cross-platform directory symlinking

Latest version **10.0.1** (published 2026-03-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install symlink-dir
pnpm add symlink-dir
yarn add symlink-dir
bun add symlink-dir
```

## Health

**Score 65/100 (B)** — status: active.

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 10.0.1 |
| Published | 2026-03-19 |
| First published | 2017-01-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.13 |
| Dependencies | 2 |
| Unpacked size | 15.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 82 |
| Author | Zoltan Kochan |
| Maintainers | zkochan |
| Keywords | symlink, symlinking, junction, directory, dir, folder |

## Links

- npm: https://www.npmjs.com/package/symlink-dir
- Repository: https://github.com/pnpm/symlink-dir
- Homepage: https://github.com/pnpm/symlink-dir#readme
- Issues: https://github.com/pnpm/symlink-dir/issues
- npm.io page: https://npm.io/package/symlink-dir

## Dependencies (2)

- [rename-overwrite](https://npm.io/package/rename-overwrite.md) ^7.0.0
- [better-path-resolve](https://npm.io/package/better-path-resolve.md) ^2.0.0

## Alternatives

- [monaco-yaml](https://npm.io/package/monaco-yaml.md) — 420.1K weekly downloads
- [@crewx/workflow](https://npm.io/package/@crewx/workflow.md) — 3.1K weekly downloads
- [yaml-cat](https://npm.io/package/yaml-cat.md) — 38 weekly downloads
- [nunjucks-in-yaml](https://npm.io/package/nunjucks-in-yaml.md) — 9 weekly downloads
- [shopify-symlinks](https://npm.io/package/shopify-symlinks.md) — 3 weekly downloads

## Recent versions

- 10.0.1 (latest) — 2026-03-19
- 5.0.0 (next) — 2021-04-11
- 10.0.0 — 2026-03-19
- 9.0.0 — 2025-10-08
- 8.0.0 — 2025-10-08
- 7.1.0 — 2025-10-07
- 7.0.0 — 2025-09-23
- 6.0.5 — 2025-03-06
- 6.0.4 — 2024-12-25
- 6.0.3 — 2024-10-29
- 6.0.2 — 2024-08-25
- 6.0.1 — 2024-07-06
- 6.0.0 — 2024-04-11
- 5.2.1 — 2023-12-24
- 5.2.0 — 2023-09-08
- … 28 more at https://npm.io/package/symlink-dir/versions

## README

# symlink-dir

> Cross-platform directory symlinking

<!--@shields('npm')-->
[![npm version](https://img.shields.io/npm/v/symlink-dir.svg)](https://www.npmjs.com/package/symlink-dir)
<!--/@-->

* Uses "junctions" on Windows if "symbolic links" is disallowed. Even though support for "symbolic links" was added in Vista+, users by default lack permission to create them
  * **⚠️ Windows Junction Warning**: On Windows, this library will create a junction even if the target is not a directory. However, Windows junctions can only point to directories, so creating a junction to a file will result in a broken, non-functioning junction. This library does not check if the target exists or is a directory. If there's a chance that the target is a file, either check it yourself before calling `symlink-dir` or set `noJunction` to `true` to prevent creating a broken junction.
* If you prefer symbolic links in Windows, [turn on the Developer Mode](https://learn.microsoft.com/windows/apps/get-started/enable-your-device-for-development#activate-developer-mode)
* Any file or directory, that has the destination name, is renamed before creating the link

## Installation

```sh
pnpm add symlink-dir
```

## CLI Usage

Lets suppose you'd like to self-require your package. You can link it to its own `node_modules`:

```sh
# from -> to
symlink-dir . node_modules/my-package
```

## API Usage

<!--@example('./example.js')-->
```js
'use strict'
const symlinkDir = require('symlink-dir')
const path = require('path')

symlinkDir('src', 'node_modules/src')
  .then(result => {
    console.log(result)
    //> { reused: false }

    return symlinkDir('src', 'node_modules/src')
  })
  .then(result => {
    console.log(result)
    //> { reused: true }
  })
  .catch(err => console.error(err))
```
<!--/@-->

## API

### `symlinkDir(target, path, opts?): Promise<{ reused: boolean, warn?: string }>`
### `symlinkDir.sync(target, path, opts?): { reused: boolean, warn?: string }`

Creates the link called `path` pointing to `target`.

Options:

* `overwrite` - *boolean* - is `true` by default. When `false`, existing files at dest are not overwritten.
* `noJunction` - *boolean* - is `false` by default. When `true`, forces creation of real symbolic links and never falls back to junctions on Windows. If symbolic links cannot be created (e.g., insufficient permissions), an error will be thrown instead of falling back to junctions.

Result:

* `reused` - *boolean* - is `true` if the symlink already existed pointing to the `target`.
* `warn` - *string* - any issues that happened during linking (it does mean a failure).

## License

[MIT](./LICENSE) © [Zoltan Kochan](https://www.kochan.io)

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