@dx-pkg/mksymlink

Cross-platform symbolic link creation tool for macOS, Windows, and Linux.

Features

• Cross-platform support - Works on macOS, Windows, and Linux
• Git-like configuration - Manage settings with mksymlink config
• Flexible symlink creation - Auto-generated or custom paths
• Configurable defaults - Set your preferred symlink directory once
• Windows symlink types - Support for file, directory, and junction
• Force overwrite - Replace existing symlinks when needed
• CLI & Programmatic API - Use from command line or Node.js

Installation

npm install -g @dx-pkg/mksymlink

Quick Start

Create symlinks in the current directory (CWD)

Generate symlinks from any source directly into your current terminal session's directory.

# Explicitly define source and target
mksymlink -s ~/projects/my-app -t .

# Creates: ~/projects/my-app -> ./my-app

# Create a symlink of the current folder inside itself (or to a target)
cd ~/projects/my-app
mksymlink -t .

# Creates: ~/projects/my-app -> ~/projects/my-app/my-app

Save to a default directory

You can configure a global destination so you don't have to specify the target path every time.

# 1. Configure the default symlink destination
mksymlink config set symlink.defaultDir ~/my-symlinks

# 2. Run without arguments to use the default directory (configured at `symlink.defaultDir`)
cd ~/projects/my-app
mksymlink

# Creates: ~/projects/my-app -> ~/my-symlinks/projects--my-app

CLI Commands

mksymlink (alias as mksymlink create)

mksymlink create

Create symlink with full control over source and target.

mksymlink create -s <source> -t <target> [--type <type>] [-f]

mksymlink config

Manage configuration settings.

mksymlink config <get|set|unset|list|info> [key] [value]

📖 Detailed Documentation:

• Create Command - Symlink creation options and examples
• Config Command - Configuration management

Programmatic API

Configuration API

import { ConfigService, ConfigCommandFactory } from '@dx-pkg/mksymlink';

// Using ConfigService directly
const config = new ConfigService();
config.set('symlink.defaultDir', '/path/to/symlinks');
const dir = config.getDefaultSymlinkDir();

// Using ConfigCommandFactory
const setCmd = ConfigCommandFactory.create({
    action: 'set',
    key: 'symlink.defaultDir',
    value: '/path/to/symlinks',
});
await setCmd.execute();

Symlink Creation API

import { MkSymlinkCommandFactory } from '@dx-pkg/mksymlink';

const command = MkSymlinkCommandFactory.create({
    source: '/path/to/source',
    target: '/path/to/target',
    type: 'dir',
    force: false,
});

await command.execute();

Advanced Usage

import { SymlinkService, PlatformDetector, ConsoleLogger } from '@dx-pkg/mksymlink';

const logger = new ConsoleLogger();
const osDetector = new PlatformDetector();
const symlinkManager = new SymlinkService(logger, osDetector);

const result = await symlinkManager.createSymlink({
    source: '/source/path',
    target: '/target/path',
    type: 'dir',
    force: true,
});

if (result.success) {
    console.log('Symlink created:', result.target);
} else {
    console.error('Failed:', result.message);
}

Windows Symlink Types

| Type | Description | Admin Required | | ---------- | -------------------------------- | -------------- | | dir | Directory symlink | Yes | | file | File symlink | Yes | | junction | Directory junction (recommended) | No |

# Recommended for directories (no admin)
mksymlink --type junction

# Requires administrator
mksymlink --type dir

📖 See: Create Command - Windows Types

Development

Build & Test

# Build
npm run build

# Test
npm test

# Lint & Format
npm run lint
npm run format

Testing CLI Commands

After building, test the CLI locally:

# Quick mode
npx mksymlink

# Config commands
npx mksymlink config set symlink.defaultDir ~/test-symlinks
npx mksymlink config list
npx mksymlink config get symlink.defaultDir
npx mksymlink config unset symlink.defaultDir
npx mksymlink config info

# Create mode
npx mksymlink create -s /path/to/source -t /path/to/target
npx mksymlink create -f
npx mksymlink create --type junction  # Windows