Node.js Reference ยท fs and fs/promises
Node.js fs.appendFile() method
Reference for fs.appendFile() and fsPromises.appendFile() in Node.js: add data to the end of a file, create it when missing, log lines safely and avoid common mistakes.
fs.appendFile() adds data to the end of a file, creating the file if it does not exist. It is writeFile() with the 'a' flag as its default, so existing content is kept and new content goes after it.
It is the quickest way to write a log line or collect results one at a time. Each call opens the file, writes and closes it again; for many writes in a row, a single open write stream is much cheaper.
import { appendFile } from 'node:fs/promises'; await appendFile('app.log', 'started\n');
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.appendFile(path, data, callback) fs.appendFile(path, data, options, callback) fsPromises.appendFile(path, data, options?): Promise<void> // path: string | Buffer | URL | integer (file descriptor) | FileHandle (promise form) // data: string | Buffer // options: string (encoding) | { encoding?, mode?, flag?, flush? }
| Name | Description |
|---|---|
path |
File to append to. A numeric descriptor must be opened for appending, and you must close it yourself. |
data |
String or Buffer to add. Anything else throws; convert numbers and objects first. |
options.encoding |
For string data, default 'utf8'. |
options.mode |
Permission bits for a file created by this call, default 0o666. |
options.flag |
Default 'a'. Use 'ax' to fail if the file exists. |
options.flush |
If true, flush to disk before closing. Default false. |
Returns: nothing (callback (error); promise resolves to undefined).
Errors: ENOENT when the folder does not exist, EACCES, EISDIR, EEXIST with 'ax', ENOSPC, and ERR_INVALID_ARG_TYPE for unsupported data.
Usage notes
- No separator is added. Include the newline yourself, or lines will run together.
- Order only if you await. Sequential
awaits write in order. Calls started without waiting can finish in any order, and large payloads to one file from many concurrent calls may interleave. Queue writes through one promise chain when order matters. - One call, one open and close. For frequent writes, hold a stream:
fs.createWriteStream(file, { flags: 'a' }), and write to it. - Appends from several processes to the same file are generally safe for small lines on local disks, because append writes go to the current end of file, but nothing guarantees one message is not split from another over network file systems.
- Log rotation is your job. The file only grows. Rotate or truncate it in a scheduled task, or use a logging library.
- Parent folders must exist (create them with
mkdirandrecursive: true). - Durability. The data is in the operating system's cache when the promise resolves. Add
flush: truewhen each entry must survive a crash. - Buffers append raw bytes. Appending a
Bufferto a UTF-8 text file is fine only if the bytes are valid UTF-8.