How to Write Files in JavaScript: Node.js & Browser Methods

Executive Summary

Writing files in JavaScript has become increasingly accessible with modern Node.js and browser APIs, yet many developers still make critical mistakes around error handling and resource management. Our analysis shows that improper file handling accounts for significant performance issues in production applications. Last verified: April 2026.

File writing in JavaScript typically involves three core approaches: the traditional Node.js fs module, Promise-based alternatives with async/await, and modern browser APIs like the File System Access API. The key to production-ready code lies in proper error handling, understanding synchronous vs. asynchronous operations, and knowing when to use streams for large files. This guide covers all three methods with real, tested code you can use immediately.

Main Data Table: File Writing Methods Comparison

Method	Use Case	Best For	Environment
fs.writeFile()	Writing entire file at once	Small to medium files (<100MB)	Node.js
fs.promises.writeFile()	Promise-based file writing	Modern async/await code	Node.js 10.0+
fs.createWriteStream()	Streaming large files	Large files (>100MB)	Node.js
File System Access API	Browser-based file writing	Web applications	Modern browsers
Blob + download	Client-side file generation	Downloadable files	All browsers

Breakdown by Experience Level

File writing complexity varies significantly based on your experience and needs. Here’s what different skill levels typically encounter:

• Beginner: Start with fs.writeFile() and fs.promises.writeFile(). These methods handle the entire operation in one call, with straightforward error handling via try/catch blocks.
• Intermediate: Graduate to streams for better performance with larger files. Learn about backpressure handling and when synchronous operations are acceptable (spoiler: rarely in production).
• Advanced: Optimize using worker threads for heavy I/O, implement sophisticated error recovery, and choose between buffering strategies for maximum throughput.

Core File Writing Methods with Code Examples

1. Using fs.promises.writeFile() (Recommended for Most Cases)

const fs = require('fs').promises;

async function writeTextFile() {
  try {
    await fs.writeFile('output.txt', 'Hello, World!', 'utf-8');
    console.log('File written successfully');
  } catch (error) {
    console.error('Error writing file:', error.message);
  }
}

writeTextFile();

Why this matters: This is the sweet spot for most use cases. It’s promise-based, works perfectly with async/await, and handles the entire write operation atomically. The ‘utf-8’ encoding is standard for text files and ensures proper character handling.

2. Writing JSON Data

const fs = require('fs').promises;

async function writeJsonFile() {
  const data = {
    name: 'John Doe',
    email: 'john@example.com',
    age: 30
  };

  try {
    await fs.writeFile(
      'user.json',
      JSON.stringify(data, null, 2),
      'utf-8'
    );
  } catch (error) {
    console.error('JSON write failed:', error);
  }
}

writeJsonFile();

The null, 2 parameters in JSON.stringify() format the output with 2-space indentation, making it readable when you inspect the file later.

3. Using Streams for Large Files

const fs = require('fs');

function writeFileWithStream() {
  const writeStream = fs.createWriteStream('large-file.txt');

  writeStream.on('error', (error) => {
    console.error('Stream error:', error);
  });

  writeStream.on('finish', () => {
    console.log('Stream writing completed');
  });

  // Write data in chunks
  for (let i = 0; i < 10000; i++) {
    writeStream.write(`Line ${i}: Some data here\n`);
  }

  writeStream.end();
}

writeFileWithStream();

Critical insight: Streams prevent memory overflow by writing data in chunks rather than loading everything into RAM. For files exceeding 100MB, streams aren't optional—they're essential.

4. Appending Data to Existing Files

const fs = require('fs').promises;

async function appendToFile() {
  try {
    await fs.appendFile('log.txt', 'New log entry\n', 'utf-8');
  } catch (error) {
    if (error.code === 'ENOENT') {
      // File doesn't exist, create it
      await fs.writeFile('log.txt', 'New log entry\n', 'utf-8');
    } else {
      throw error;
    }
  }
}

appendToFile();

5. Browser-Based File Writing with Blob

function downloadTextFile() {
  const content = 'This is my file content';
  const blob = new Blob([content], { type: 'text/plain' });
  const url = URL.createObjectURL(blob);
  
  const link = document.createElement('a');
  link.href = url;
  link.download = 'myfile.txt';
  document.body.appendChild(link);
  link.click();
  document.body.removeChild(link);
  URL.revokeObjectURL(url);
}

downloadTextFile();

Comparison Section: Alternative File Writing Approaches

Approach	Pros	Cons	When to Use
fs.writeFileSync()	Simple, blocking, immediate completion	Blocks event loop, poor performance in production	CLI tools, scripts only—never production servers
fs.createWriteStream()	Memory efficient, handles huge files	More complex error handling, backpressure management	Large files, continuous logging, high throughput
fs.promises.writeFile()	Promise-based, async/await compatible, modern	Entire file loaded into memory	Most modern applications, small-medium files
File System Access API	Works in browsers, user permission model	Limited browser support, security sandboxed	Web apps needing local file system access
Third-party libraries (better-fs, etc.)	Extra features, sometimes cleaner API	Additional dependency, maintenance overhead	Only when standard library falls short

Key Factors When Writing Files in JavaScript

1. Error Handling is Non-Negotiable

The most common production failure mode is missing error handling. Always wrap file operations in try/catch blocks. Disk full errors, permission denied, and path errors are common real-world scenarios. When you don't handle these, your application silently fails and data loss occurs.

2. Choose Async Operations in Server Code

Synchronous file operations like fs.writeFileSync() block the entire Node.js event loop. Even a single synchronous write can delay all other requests by milliseconds—multiply that across thousands of concurrent users and you have a serious performance problem. Use promises or streams exclusively in production servers.

3. Stream When File Size Exceeds 100MB

Writing a 500MB file with writeFile() loads the entire contents into memory simultaneously. On a server handling multiple concurrent requests, this exhausts RAM quickly. Streams write in manageable chunks and backpressure automatically, maintaining consistent memory usage regardless of file size.

4. Always Close Resources Explicitly

Write streams should always call .end() or use the finished promise API. Failing to close creates open file descriptors that can eventually exhaust system limits. Every unclosed file is a resource leak waiting to fail at peak traffic.

5. Understand Atomic vs. Non-Atomic Operations

File writes might not be atomic—if your process crashes mid-write, you get a partial or corrupted file. For critical data, write to a temporary file first, then rename it atomically. This ensures readers never see incomplete data.

Historical Trends

File handling in JavaScript has evolved significantly. In early Node.js versions (pre-10.0), developers relied entirely on callback-based APIs, creating what was called "callback hell." The fs.promises API arrived in Node.js 10 (2018), making async/await possible. Modern Node.js 16+ includes the File System Access API in browsers, opening new possibilities for web applications.

The trend is clear: the JavaScript ecosystem is moving toward promise-based and stream-based approaches. Callbacks haven't disappeared entirely, but they're considered legacy patterns now. If you're reviewing older codebases, expect to see callback-heavy file operations; when writing new code, stick with promises and async/await.

Expert Tips Based on Real-World Usage

Tip 1: Validate File Paths Before Writing

Always sanitize and validate file paths to prevent directory traversal attacks. A malicious input like ../../../etc/passwd could write to sensitive system locations. Use path normalization and whitelist allowed directories.

Tip 2: Implement Backpressure Handling for Streams

function writeWithBackpressure() {
  const writeStream = fs.createWriteStream('output.txt');
  
  for (let i = 0; i < 1000000; i++) {
    const canContinue = writeStream.write(`Line ${i}\n`);
    
    if (!canContinue) {
      console.log('Backpressure detected, pausing writes');
      break; // Stop writing until drain event
    }
  }
  
  writeStream.on('drain', () => {
    console.log('Stream drained, resuming writes');
    // Resume writing in real application
  });
}

This pattern prevents memory buildup when the write stream can't keep pace with your write calls.

Tip 3: Log File Operations in Production

Add structured logging to track file write operations. Know when writes fail, how long they take, and what errors occurred. This becomes invaluable during incident response when users report missing data.

Tip 4: Use File Locking for Concurrent Writes

If multiple processes write to the same file, implement file locking to prevent corruption. Libraries like proper-lockfile provide this functionality reliably.

Tip 5: Test Edge Cases Thoroughly

Write tests covering: disk full scenarios, permission errors, network failures (if writing to remote storage), file path conflicts, and concurrent writes. Don't assume the happy path will always succeed.

FAQ

Q: Should I use writeFile() or createWriteStream()?

Use writeFile() for files under 100MB and when you have the complete content available. Use createWriteStream() for larger files or when data arrives in chunks (like from a database cursor or API response stream). The memory difference becomes critical around 500MB+ files on servers with limited RAM.

Q: Why does my file write silently fail?

Without try/catch blocks or error event handlers, file write failures go unnoticed. Always attach error handlers to streams and wrap promises in try/catch. Common silent failures include disk full, permission denied, and invalid path errors.

Q: Can I write files from browser JavaScript?

Not to arbitrary locations. Browsers sandbox file system access for security. You can: download files (Blob + anchor), use File System Access API (with user permission), or upload to a server. The File System Access API is modern and works in Chrome 86+ and Edge 86+, but not yet in Firefox.

Q: How do I write without overwriting existing files?

Check if the file exists first using fs.promises.access(), or use the { flag: 'a+' } option to append instead. For atomic writes without overwriting, write to a temporary file, then rename it: await fs.promises.rename('temp.txt', 'final.txt').

Q: What's the performance impact of encoding conversion?

Specifying the encoding (like 'utf-8') is handled efficiently at the C++ level in Node.js. The real performance cost comes from string manipulation in JavaScript before writing. For maximum performance with large files, work with Buffers directly instead of strings.

Conclusion

Writing files in JavaScript is straightforward when you understand the three key methods: use fs.promises.writeFile() for typical cases, streams for large files, and the File System Access API for browser applications. The critical success factors are robust error handling, choosing async operations in production, and understanding the memory implications of your approach.

Most developers fail not because they don't know how to write files, but because they skip error handling, use synchronous operations in async contexts, or overlook resource cleanup. Start with the promise-based fs.promises API, implement comprehensive error handling immediately, and graduate to streams only when profiling shows it's necessary. Your future self—and your users—will thank you when files actually persist reliably.