Node.js Reference ยท fs and fs/promises
Node.js fs.symlink() method
Reference for fs.symlink() in Node.js: create symbolic links, how relative targets resolve, dangling links, the type argument on Windows and common errors.
fs.symlink(target, path, type, callback) creates a symbolic link (symlink): a tiny file at path whose content is the path target. When a program opens the link, the operating system transparently follows it to the target.
Note the argument order: the target comes first, then the location of the new link. It is the same order as ln -s target linkname, and the reverse of what many people expect from a "copy" style call.
import fs from "node:fs"; fs.symlinkSync("releases/v2", "current");
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
fs.symlink(target, path[, type], callback) fs.symlinkSync(target, path[, type]): undefined fsPromises.symlink(target, path[, type]): Promise<undefined>
| Name | Description |
|---|---|
target |
The text stored in the link. Relative paths are resolved against the directory that contains the link. The target does not need to exist. |
path |
Where to create the link. Must not already exist. |
type |
"file", "dir" or "junction". Used only on Windows; ignored elsewhere. Default: detected from the target if it exists, otherwise "file". |
Returns: undefined.
Errors: EEXIST if path already exists, ENOENT if the folder for the link does not exist, EPERM on Windows without the privilege to create links, EACCES without write permission to the folder.
Usage notes
- Relative targets are the top mistake.
symlink("data.txt", "sub/link")points atsub/data.txt, not at./data.txt. Build the target relative to the link's folder withpath.relative(path.dirname(link), real). - Dangling links are legal. Node does not check that the target exists. A broken link makes
statandreadFilefail withENOENT, whilelstatandreadlinkstill work. - There is no overwrite option. To replace a link atomically, create a new link under a temporary name and
renameit over the old one. - Windows: creating links needs administrator rights or Developer Mode. Pass
"junction"for directories to avoid that; junctions require absolute targets, and Node converts them. Pass"dir"correctly if the target does not exist yet, because the type cannot be guessed. - Symlinks versus hard links: a symlink is a pointer by name and works across file systems and for directories. A hard link (
fs.link()) is another name for the same data and needs the same file system. - Security: when you unpack or serve user-supplied paths, a link can point outside the folder you meant. Resolve with
fs.realpath()and check the prefix. - Deleting a link with
unlinkremoves only the link, never the target.