Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Buffers and Encoding

The Node.js File class

Reference for the Node.js File class from node:buffer: a Blob with a name and a modified time, how to construct it, read it, slice it and how it differs from Blob.

File is a Blob with two extra properties: a name and a lastModified time. It follows the web platform API of the same name, so code written for the browser can run in Node.js. It is available as a global and can also be imported from node:buffer.

A File does not touch the file system. Despite the name it is an immutable, in-memory (or lazily read) chunk of bytes plus metadata, useful for building FormData bodies, passing data between APIs that expect the web File shape and testing upload code. To read a real file from disk as a Blob, use fs.openAsBlob(path), which returns a Blob.

NODE
const file = new File(["hello"], "greeting.txt", { type: "text/plain" });
file.name; // "greeting.txt"
file.size; // 5

Try it

Node.js Creating and reading a File

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.

Node.js Parts, defaults and type normalization

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

NODE
import { File } from "node:buffer";

new File(fileBits, fileName, options)
// fileBits: Array of string | ArrayBuffer | TypedArray | DataView | Blob | File
// options: { type?: string, lastModified?: number, endings?: "transparent" | "native" }
Name Description
fileBits An array of parts that are concatenated, in order, to make the content.
fileName The name of the file. Required. It is converted to a string and not validated or split on slashes.
options.type MIME type. Lowercased; a string with characters outside printable ASCII becomes "". Default "".
options.lastModified Milliseconds since the Unix epoch. Default: the current time.
options.endings Line-ending handling for string parts: "transparent" (default) keeps them, "native" converts \n to the platform's ending.

Properties: name, lastModified, and the inherited size and type.

Methods (from Blob): text(), arrayBuffer(), bytes(), stream() and slice(start, end, type). All reading methods return promises.

Errors and edge cases:

  • Fewer than two arguments throws ERR_MISSING_ARGS.
  • A fileBits that is not an array (for example a plain string) throws ERR_INVALID_ARG_TYPE. Elements of other types are converted to strings, so {} becomes "[object Object]".
  • slice() returns a Blob, not a File, so the name and modified time are not carried over.
  • JSON.stringify(file) gives {}; the properties are on the prototype and the content is not serializable.

Usage notes

  • Immutable: the content is copied at construction (for strings and buffers). Changing an Uint8Array afterwards does not change the file.
  • Uses in Node.js: appending to FormData (form.append("upload", file)), passing to fetch() bodies and APIs such as Response or URL.createObjectURL(). fetch() with a FormData containing a File sends the name in the Content-Disposition header.
  • Blob for anonymous data: use Blob when no name makes sense; use File when the receiver expects name. A File is also accepted anywhere a Blob is.
  • Memory: each reading method makes its own copy. Prefer stream() for large content to avoid holding everything at once.
  • Browser-like but not identical: there is no webkitRelativePath, and File objects cannot come from user selection since there is no file picker.
  • Cloning: a File can be passed through structuredClone() and postMessage() to worker threads on current Node.js versions; test it on your version before relying on it.
  • Stability: File has been global since Node.js 20.