The Secret Life of JavaScript: The Sandbox

Escaping the walled garden with the File System Access API

#JavaScript #WebPerformance #Frontend #FileSystemAPI

---

Margaret is a senior software engineer. Timothy is her junior colleague. They work in a grand Victorian library in London — the kind of place where code quality is the unspoken objective, and craftsmanship is the only thing that matters.

Episode 34

The Cluttered Folder

Timothy opened his local Downloads folder and sighed. The directory was a complete mess, filled with a massive list of almost identical text files: diagnostic-log.txt, diagnostic-log (1).txt, diagnostic-log (2).txt, all the way down to (14).txt.

"The export feature is working, but the developer experience is terrible," Timothy explained to Margaret as she walked up with her dark roast coffee. "Every time the user clicks 'Export Logs', the browser generates a Blob and forces an <a download> click. If they update the log and export it again ten minutes later, the browser just downloads a brand new copy."

The Walled Garden

Margaret looked at the messy directory. "Why don't you just overwrite the original file when they click save the second time?"

"I can't," Timothy said, shaking his head. "The browser is a walled garden. It doesn't have access to the operating system's native file system for security reasons. Every time I trigger a download, the browser treats it as a completely isolated, brand new event."

"Is it still a walled garden?" Margaret asked, taking a sip of her coffee. "Or have you just stopped checking the gates?"

Timothy frowned. "What do you mean?"

"The <a download> attribute was a great hack for 2014," Margaret explained. "But you are treating the browser like a simple document viewer. What if we treated it like a native desktop application?"

The File Handle

Margaret picked up a dry-erase marker and stepped to the whiteboard. She wrote showSaveFilePicker().

"Welcome to the File System Access API," Margaret said. "Instead of blindly throwing files over the browser wall into the Downloads folder, we can explicitly ask the user for permission to access a specific file on their hard drive. Once they grant us permission, the operating system hands the JavaScript engine a persistent file handle."

"And once we have the handle?" Timothy asked.

"Then the wall comes down," Margaret smiled. "We can open a writable stream and write data directly to that exact file on their local disk. No more (1).txt duplicates."

The Feature Detection

"This sounds incredible," Timothy said. "But what if a user is on Safari or Firefox? Do they support it yet?"

"That is the reality of the bleeding edge," Margaret noted. "The File System Access API is currently supported in Chromium-based browsers like Chrome and Edge. For the rest, the wall is still firmly up."

"So the application just breaks for them?" Timothy asked.

"Only if you don't check the gates first," Margaret corrected. "You use feature detection. If the browser supports the modern API, you use the file handle. If it doesn't, you gracefully fall back to the legacy download pattern."

The Writable Stream

Timothy completely scrapped his legacy download logic. Following Margaret's guidance, he tapped into the window object to check for feature support, invoking the file picker when available, and leveraging the streaming architecture he had been mastering all week to pipe the data straight to the disk.

// main.js - Writing Directly to the Local File System
async function saveDiagnosticLog(logText) {
  // 1. Feature Detection: Check if the modern API is supported
  if ('showSaveFilePicker' in window) {
    try {
      // 2. Prompt the user to select or create a file
      const fileHandle = await window.showSaveFilePicker({
        suggestedName: 'diagnostic-log.txt',
        types: [{
          description: 'Text Files',
          accept: { 'text/plain': ['.txt'] },
        }],
      });

      // 3. Request a writable stream to that specific local file
      const writableStream = await fileHandle.createWritable();

      // 4. Write the payload directly to the hard drive
      await writableStream.write(logText);
      
      // 5. Close the stream to release the file lock
      await writableStream.close();

    } catch (error) {
      // Safely catch AbortErrors if the user clicks "Cancel" in the native dialog
      console.error('File save cancelled or failed:', error);
    }
  } else {
    // 6. Fallback: Use the legacy <a download> pattern for Safari/Firefox
    const blob = new Blob([logText], { type: 'text/plain' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'diagnostic-log.txt';
    a.click();
    URL.revokeObjectURL(url);
  }
}

Timothy refreshed the dashboard and clicked the export button. Instead of a silent download, a native Windows save dialog appeared. He selected his documents folder and saved the file.

Ten minutes later, the log data updated on the screen. He clicked export again. This time, there was no prompt, and no duplicate file was created. The JavaScript engine securely streamed the new data directly into the exact same file handle, cleanly overwriting the contents.

By utilizing the File System Access API and respecting feature detection, Timothy bridged the gap between the web application and the operating system, bringing true native IDE capabilities straight to the browser without breaking older clients.

---

Aaron Rose is a software engineer and technology writer at tech-reader.blog. 

Catch up on the latest explainer videos, podcasts, and industry discussions below.