finder-alias

Resolve and create macOS Finder aliases

A Finder alias is a file that points to another file or folder, like a symlink, but it keeps working when the target is moved. Node.js cannot follow aliases, because the file system sees them as regular files.

It uses the CoreFoundation bookmark APIs through node:ffi, so it is fast and has no native dependencies.

Install

npm install finder-alias

Requires Node.js 26.9 or later.

Usage

import {isFinderAlias, resolveFinderAlias, createFinderAlias} from 'finder-alias';

isFinderAlias('/Users/sindresorhus/Desktop/Unicorn alias');
//=> true

resolveFinderAlias('/Users/sindresorhus/Desktop/Unicorn alias');
//=> '/Users/sindresorhus/Documents/Unicorn'

createFinderAlias('/Users/sindresorhus/Documents/Rainbow', '/Users/sindresorhus/Desktop/Rainbow alias');

API

The methods are synchronous. Resolving an alias takes a few milliseconds.

isFinderAlias(path)

Returns a boolean of whether the path is a Finder alias.

Symlinks are not Finder aliases. Returns false if the path does not exist or if the platform is not macOS.

Throws if the path cannot be checked, for example because of missing permission.

resolveFinderAlias(path)

Returns the real path of the target.

It works like fs.realpathSync.native(), but it also resolves the path when it is a Finder alias. It continues until the path is neither, so it handles an alias to a symlink, a symlink to an alias, and an alias to an alias.

Only the last part of the path can be a Finder alias. macOS does not follow aliases in the parent folders of a path.

On other platforms than macOS, it only resolves symlinks.

Throws if the path does not exist, if the target of an alias cannot be found, or if the aliases form a cycle.

createFinderAlias(targetPath, aliasPath)

Create a Finder alias at aliasPath that points to targetPath.

Throws if the target does not exist, if the alias path exists, if the folder of the alias path does not exist, or if the platform is not macOS.

CLI

npm install --global finder-alias

finder-alias --help

  Resolve and create macOS Finder aliases

  Usage
    $ finder-alias <path>
    $ finder-alias --create <target> <alias>
    $ finder-alias --check <path>

  Options
    --create  Create a Finder alias to the target
    --check   Exit with code 0 if the path is a Finder alias, and 2 if not

  Examples
    $ finder-alias 'Unicorn alias'
    /Users/sindresorhus/Documents/Unicorn

    $ finder-alias --create ~/Documents/Unicorn ~/Desktop/'Unicorn alias'

FAQ

Why does it print an experimental warning?

node:ffi is still experimental in Node.js. The package loads it the first time it reads a regular file to find out if it is an alias, or creates an alias, on macOS. The warning shows at that time, once.

Does it mount network volumes?

No. If the target is on a volume that is not mounted, resolving the alias throws.

Is it safe in a folder that another local user can write to?

No. Checking that a path is a regular file and reading the file happen in two steps. Another local user with write access to the folder can swap the file in between, for example with a named pipe, which makes the process wait forever. Use a folder that only you can write to.