symlink-dir

Cross-platform directory symlinking

• 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
• Any file or directory, that has the destination name, is renamed before creating the link

Installation

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:

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

API Usage

'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 © Zoltan Kochan