nodejs
diff --git a/‎doc/api/fs.md‎
Lines changed: 23 additions & 0 deletions b/‎doc/api/fs.md‎
Lines changed: 23 additions & 0 deletions
@@ -3156,6 +3156,28 @@ system requests but rather the internal buffering `fs.readFile` performs.
    the call to `fs.readFile()` with the same file descriptor, would give
    `'World'`, rather than `'Hello World'`.
 
+### Performance Considerations
+
+The `fs.readFile()` method asynchronously reads the contents of a file into
+memory one chunk at a time, allowing the event loop to turn between each chunk.
+This allows the read operation to have less impact on other activity that may
+be using the underlying libuv thread pool but means that it will take longer
+to read a complete file into memory.
+
+The additional read overhead can vary broadly on different systems and depends
+on the type of file being read. If the file type is not a regular file (a pipe
+for instance) and Node.js is unable to determine an actual file size, each read
+operation will load on 64kb of data. For regular files, each read will process
+512kb of data.
+
+For applications that require as-fast-as-possible reading of file contents, it
+is better to use `fs.read()` directly and for application code to manage
+reading the full contents of the file itself.
+
+The Node.js GitHub issue [#25741][] provides more information and a detailed
+analysis on the performance of `fs.readFile()` for multiple file sizes in
+different Node.js versions.
+
 ## `fs.readFileSync(path[, options])`
 <!-- YAML
 added: v0.1.8
@@ -6212,6 +6234,7 @@ through `fs.open()` or `fs.writeFile()` or `fsPromises.open()`) will fail with
 A call to `fs.ftruncate()` or `filehandle.truncate()` can be used to reset
 the file contents.
 
+[#25741]: https://github.com/nodejs/node/issues/25741
 [Caveats]: #fs_caveats
 [Common System Errors]: errors.md#errors_common_system_errors
 [FS constants]: #fs_fs_constants_1