Chapter 5: File System Access - Reading, Writing, and Managing Data

Welcome back, future Puter.js masters! In our previous chapters, we laid the groundwork by understanding what Puter.js is and how to interact with its core APIs. Now, it’s time to make our applications truly useful by giving them memory: the ability to store and retrieve data.

In this chapter, we’ll dive deep into the Puter.js File System. This is where your applications can read configuration files, save user preferences, store game progress, or even manage complex application-specific data. We’ll learn how to perform essential file operations like reading content, writing new data, creating and listing directories, and even cleaning up files and folders. By the end of this chapter, you’ll be able to equip your Puter.js apps with persistent storage, making them more dynamic and user-friendly. Ready to give your apps a memory? Let’s go!

The Puter.js File System: Your App’s Private Storage

Imagine your Puter.js application as a mini-operating system within the larger Puter.js environment. Just like a desktop application needs a place to store its data, your Puter.js app gets its own dedicated, sandboxed file system. This isn’t your computer’s local hard drive; it’s an abstract, virtual file system managed by Puter.js itself, ensuring security and isolation between applications.

Why a Sandboxed File System?

This isolated approach is crucial for several reasons:

1. Security: Your app can only access files within its designated sandbox, preventing it from interfering with other apps or the underlying Puter.js system.
2. Portability: Files stored this way are tied to your Puter.js app, making it easy to deploy, migrate, or even share your application without worrying about local file paths.
3. Simplicity: Puter.js handles the complexities of storage, letting you focus on your application logic.

Introducing Puter.fs: The File System API

All interactions with the Puter.js file system happen through the global Puter.fs object. This object provides a set of asynchronous methods that mirror common file system operations you might be familiar with from Node.js or modern browser APIs. Remember, since file operations can take time (especially across a network), these methods are asynchronous and typically return Promises. This means we’ll be using async/await extensively!

Understanding Paths

Within the Puter.js file system, paths look very similar to traditional Unix-like paths (e.g., /my/folder/file.txt).

• App-Specific Storage: Your application’s default working directory is usually /apps/<your-app-id>/. This is where your app’s static assets are located and where you’ll typically store app-specific data.
• User-Specific Storage (Advanced): For data that needs to persist across different apps for a single user, Puter.js also offers mechanisms to access user-specific directories, often under /home/<user-id>/. We’ll focus on app-specific storage for now, as it’s the primary way applications manage their own data.

Step-by-Step Implementation: Working with Files and Directories

Let’s roll up our sleeves and start coding! We’ll begin with the most fundamental operations: reading and writing files.

1. Writing Your First File

To write content to a file, we use Puter.fs.writeFile(). This method takes the file path and the content as arguments. If the file doesn’t exist, it will be created. If it does exist, its content will be overwritten.

Let’s create a simple text file named hello.txt in your app’s root directory.

// index.js (or your main application script)

async function writeHelloFile() {
    const filePath = '/apps/my-first-app/hello.txt'; // Assuming your app ID is 'my-first-app'
    const content = 'Hello, Puter.js File System! This is my first file.';

    try {
        await Puter.fs.writeFile(filePath, content);
        console.log(`Successfully wrote to ${filePath}`);
    } catch (error) {
        console.error(`Error writing file: ${error.message}`);
    }
}

// Call the function to execute it
writeHelloFile();

Explanation:

• async function writeHelloFile(): We wrap our file operation in an async function because Puter.fs.writeFile returns a Promise.
• const filePath = '/apps/my-first-app/hello.txt';: We define the full path to our file. Remember to replace my-first-app with your actual Puter.js application ID if it’s different.
• await Puter.fs.writeFile(filePath, content);: This is the core call. await pauses the function execution until the writeFile Promise resolves (meaning the file has been written).
• try...catch: It’s crucial to wrap asynchronous operations that might fail (like file I/O) in a try...catch block to handle potential errors gracefully.

Now, if you run this code within your Puter.js application, you’ll see a console message confirming the write operation.

2. Reading Your First File

Now that we’ve written a file, let’s read its content back using Puter.fs.readFile(). This method takes the file path and an optional encoding (defaults to utf8 for text files).

Let’s read the hello.txt file we just created.

// index.js (add to the previous code, or create a new function)

async function readHelloFile() {
    const filePath = '/apps/my-first-app/hello.txt'; // Same path as before

    try {
        const content = await Puter.fs.readFile(filePath, { encoding: 'utf8' });
        console.log(`Content of ${filePath}:\n${content}`);
    } catch (error) {
        console.error(`Error reading file: ${error.message}`);
    }
}

// Call this function after writing the file
writeHelloFile().then(() => readHelloFile()); // Ensure write happens before read

Explanation:

• await Puter.fs.readFile(filePath, { encoding: 'utf8' });: We await the readFile Promise. The { encoding: 'utf8' } option ensures the content is returned as a human-readable string. Without it, you might get a Buffer object (useful for binary data).
• writeHelloFile().then(() => readHelloFile());: We chain the calls to ensure readHelloFile only runs after writeHelloFile has successfully completed. This is a common pattern for dependent asynchronous operations.

You should now see the “Hello, Puter.js File System! This is my first file.” message printed to your console. How cool is that? Your app now has memory!

3. Managing Directories: Creating and Listing

Files often live inside directories. Puter.fs provides methods to create new directories (mkdir) and list their contents (readdir).

Let’s create a new directory called data and then list the contents of our app’s root directory.

// index.js (add to previous code)

async function manageDirectories() {
    const appRootPath = '/apps/my-first-app'; // Your app's root
    const dataDirPath = `${appRootPath}/data`; // New directory path

    try {
        // Create the 'data' directory
        await Puter.fs.mkdir(dataDirPath);
        console.log(`Directory created: ${dataDirPath}`);

        // List contents of the app's root directory
        const contents = await Puter.fs.readdir(appRootPath);
        console.log(`Contents of ${appRootPath}:`, contents); // Should show ['hello.txt', 'data']

    } catch (error) {
        // Handle error if directory already exists or other issues
        if (error.code === 'EEXIST') {
            console.warn(`Directory ${dataDirPath} already exists.`);
            const contents = await Puter.fs.readdir(appRootPath);
            console.log(`Contents of ${appRootPath}:`, contents);
        } else {
            console.error(`Error managing directories: ${error.message}`);
        }
    }
}

// Call this after reading the file
writeHelloFile()
    .then(() => readHelloFile())
    .then(() => manageDirectories());

Explanation:

• await Puter.fs.mkdir(dataDirPath);: This creates the data directory. If it already exists, it will throw an error, which we catch.
• await Puter.fs.readdir(appRootPath);: This returns an array of strings, where each string is the name of a file or directory directly within appRootPath.

After running this, your console should show that the data directory was created (or already existed) and then list ['hello.txt', 'data'] as the contents of your app’s root.

4. Deleting Files and Directories

Cleaning up is just as important as creating! Puter.fs offers methods to remove files (unlink) and directories (rmdir, rm).

• Puter.fs.unlink(filePath): Deletes a specific file.
• Puter.fs.rmdir(dirPath): Deletes an empty directory. If the directory contains files or other directories, it will fail.
• Puter.fs.rm(path, { recursive: true }) (Modern approach): This is the recommended way to delete files or directories, even non-empty ones. The { recursive: true } option makes it delete contents automatically.

Let’s clean up hello.txt and the data directory. First, we’ll put a file inside data to demonstrate recursive deletion.

// index.js (add to previous code)

async function cleanupFiles() {
    const appRootPath = '/apps/my-first-app';
    const dataDirPath = `${appRootPath}/data`;
    const innerFilePath = `${dataDirPath}/config.json`;

    try {
        // 1. Ensure 'data' directory exists and create a file inside it
        await Puter.fs.mkdir(dataDirPath, { recursive: true }); // Ensure parent dirs exist
        await Puter.fs.writeFile(innerFilePath, JSON.stringify({ theme: 'dark', notifications: true }));
        console.log(`Created ${innerFilePath} for demonstration.`);

        // 2. Delete the original 'hello.txt' file
        await Puter.fs.unlink(`${appRootPath}/hello.txt`);
        console.log(`Deleted ${appRootPath}/hello.txt`);

        // 3. Delete the 'data' directory and its contents recursively
        await Puter.fs.rm(dataDirPath, { recursive: true });
        console.log(`Recursively deleted directory: ${dataDirPath}`);

        // 4. Verify contents of app root (should be empty now)
        const remainingContents = await Puter.fs.readdir(appRootPath);
        console.log(`Remaining contents of ${appRootPath}:`, remainingContents);

    } catch (error) {
        console.error(`Error during cleanup: ${error.message}`);
    }
}

// Call this after all previous operations
writeHelloFile()
    .then(() => readHelloFile())
    .then(() => manageDirectories())
    .then(() => cleanupFiles());

Explanation:

• await Puter.fs.mkdir(dataDirPath, { recursive: true });: The recursive: true option ensures that if any parent directories in dataDirPath don’t exist, they will be created. This is a handy option for mkdir.
• await Puter.fs.rm(dataDirPath, { recursive: true });: This is the star of the show for deletion! It removes dataDirPath and all its contents, including config.json without needing to delete config.json separately. This is a powerful and convenient method.

After running this, your app’s root directory should be empty again, demonstrating effective file system management.

5. Checking Existence and Getting Metadata (stat)

Sometimes you just need to know if a file or directory exists, or get more details about it. Puter.fs.stat() is your friend here. It returns a Stats object with information like isFile(), isDirectory(), size, mtime (modification time), etc.

// index.js (add to previous code, or create a new script for this)

async function checkFileStats() {
    const filePath = '/apps/my-first-app/important-note.txt';
    const dirPath = '/apps/my-first-app/documents';

    try {
        // Create a file and a directory for demonstration
        await Puter.fs.mkdir(dirPath, { recursive: true });
        await Puter.fs.writeFile(filePath, 'Remember to buy milk!');

        // Check if the file exists and get its stats
        const fileStats = await Puter.fs.stat(filePath);
        console.log(`Is '${filePath}' a file? ${fileStats.isFile()}`);
        console.log(`Size of '${filePath}': ${fileStats.size} bytes`);
        console.log(`Last modified: ${fileStats.mtime}`);

        // Check if the directory exists and get its stats
        const dirStats = await Puter.fs.stat(dirPath);
        console.log(`Is '${dirPath}' a directory? ${dirStats.isDirectory()}`);

        // Attempt to stat a non-existent path
        try {
            await Puter.fs.stat('/apps/my-first-app/non-existent.txt');
        } catch (error) {
            if (error.code === 'ENOENT') {
                console.log("'/apps/my-first-app/non-existent.txt' does not exist (as expected).");
            } else {
                throw error; // Re-throw if it's an unexpected error
            }
        }

    } catch (error) {
        console.error(`Error checking file stats: ${error.message}`);
    } finally {
        // Clean up
        await Puter.fs.rm(filePath, { force: true }).catch(() => {}); // ignore if already deleted
        await Puter.fs.rm(dirPath, { recursive: true, force: true }).catch(() => {}); // ignore if already deleted
        console.log("Cleanup complete for checkFileStats.");
    }
}

// Call this function
checkFileStats();

Explanation:

• await Puter.fs.stat(path);: This is the core method. It returns a Stats object.
• fileStats.isFile() and dirStats.isDirectory(): These are convenient methods on the Stats object to check the type of the path.
• fileStats.size, fileStats.mtime: Accessing other metadata properties.
• Error Handling for ENOENT: When stat is called on a non-existent path, it throws an error with code: 'ENOENT' (Error NO ENtry). This is how you programmatically check if a file/directory exists by attempting to stat it and catching this specific error.
• finally block: Ensures cleanup happens regardless of whether errors occurred in the try block. force: true for rm is a useful addition for robust cleanup, ensuring it tries to delete even if permissions are tricky, though within your own app’s sandbox, this is less critical.

Mini-Challenge: User Preferences Manager

Let’s put your new file system skills to the test!

Challenge: Create a simple Puter.js application that allows a user to set a “favorite color” and a “display name.” These preferences should be saved to a JSON file named preferences.json in your app’s data directory. When the app starts, it should read these preferences and display them. If no preferences are found, it should use default values and save them.

Steps:

1. Define a default preferences object.
2. Define the preferences.json file path.
3. On app startup:
   • Try to read preferences.json.
   • If successful, parse the JSON and use those preferences.
   • If the file doesn’t exist (catch ENOENT from readFile), use the default preferences.
4. Implement a function to update preferences: This function should take new color and name values, update the preferences object, and write the updated object back to preferences.json.
5. Display the current preferences in the console after reading/setting them.

Hint: Remember JSON.stringify() to convert a JavaScript object to a JSON string for writing, and JSON.parse() to convert a JSON string back to a JavaScript object after reading.

// Mini-Challenge Placeholder - Try to complete this yourself!
async function runPreferencesManager() {
    const preferencesFilePath = '/apps/my-first-app/data/preferences.json';
    const defaultPreferences = {
        favoriteColor: 'blue',
        displayName: 'Puter User'
    };
    let currentPreferences = { ...defaultPreferences }; // Start with defaults

    // Function to load preferences
    async function loadPreferences() {
        try {
            const fileContent = await Puter.fs.readFile(preferencesFilePath, { encoding: 'utf8' });
            currentPreferences = JSON.parse(fileContent);
            console.log("Loaded preferences:", currentPreferences);
        } catch (error) {
            if (error.code === 'ENOENT') {
                console.log("No preferences file found. Using default preferences.");
                await savePreferences(); // Save defaults if no file exists
            } else {
                console.error("Error loading preferences:", error);
            }
        }
    }

    // Function to save preferences
    async function savePreferences() {
        try {
            // Ensure the directory exists before writing the file
            const dirPath = preferencesFilePath.substring(0, preferencesFilePath.lastIndexOf('/'));
            await Puter.fs.mkdir(dirPath, { recursive: true });

            await Puter.fs.writeFile(preferencesFilePath, JSON.stringify(currentPreferences, null, 2));
            console.log("Preferences saved:", currentPreferences);
        } catch (error) {
            console.error("Error saving preferences:", error);
        }
    }

    // Function to update preferences (and save them)
    async function updatePreferences(newColor, newName) {
        currentPreferences.favoriteColor = newColor;
        currentPreferences.displayName = newName;
        await savePreferences();
    }

    // --- Application Logic ---
    console.log("--- Starting Preferences Manager ---");

    // 1. Load preferences on startup
    await loadPreferences();

    // 2. Display current preferences
    console.log(`Current Favorite Color: ${currentPreferences.favoriteColor}`);
    console.log(`Current Display Name: ${currentPreferences.displayName}`);

    // 3. Simulate updating preferences after some user interaction
    console.log("\n--- Updating Preferences ---");
    await updatePreferences('green', 'Master Puter');

    // 4. Display updated preferences (re-load to confirm persistence)
    console.log("\n--- Re-loading to confirm update ---");
    await loadPreferences();
    console.log(`Updated Favorite Color: ${currentPreferences.favoriteColor}`);
    console.log(`Updated Display Name: ${currentPreferences.displayName}`);

    console.log("--- Preferences Manager Finished ---");
}

runPreferencesManager();

Common Pitfalls & Troubleshooting

1. Forgetting await for Puter.fs methods: Since all Puter.fs methods return Promises, you must await them inside an async function or use .then() to handle their resolution. Forgetting await will lead to your code continuing execution before the file operation is complete, often resulting in “file not found” errors or incorrect data.
   • Symptom: Code runs too fast, subsequent file operations fail.
   • Fix: Always use await with Puter.fs methods.
2. Incorrect Paths: Misspelling a path, or using a relative path when an absolute path is expected, is a common issue. Remember your app’s root is /apps/<your-app-id>/.
   • Symptom: ENOENT (No such file or directory) errors even when you’re sure the file should exist.
   • Fix: Double-check your paths. Use console.log() to print the full path being used before the Puter.fs call.
3. Permissions Errors: While Puter.js sandboxes help, you might still encounter permission issues if you try to write to system-level paths or paths outside your app’s designated storage.
   • Symptom: EACCES (Permission denied) errors.
   • Fix: Ensure you are operating within your app’s allowed directories, typically /apps/<your-app-id>/ and subdirectories.
4. Deleting Non-Empty Directories with rmdir(): The Puter.fs.rmdir() method only works on empty directories. Trying to delete a directory with contents will throw an error.
   • Symptom: ENOTEMPTY (Directory not empty) error when using rmdir.
   • Fix: Use Puter.fs.rm(path, { recursive: true }) for deleting directories that might contain files or other subdirectories.

Summary

Congratulations! You’ve successfully navigated the Puter.js file system and learned how to give your applications persistent memory. Here’s a quick recap of what we covered:

• Puter.js File System: An isolated, sandboxed storage mechanism for your applications, accessible via the Puter.fs global object.
• Asynchronous Operations: All file system operations are asynchronous and return Promises, requiring async/await for proper handling.
• Reading Files: Use Puter.fs.readFile(path, { encoding: 'utf8' }) to retrieve file content.
• Writing Files: Use Puter.fs.writeFile(path, content) to create or overwrite files.
• Managing Directories:
  • Puter.fs.mkdir(path, { recursive: true }) to create directories.
  • Puter.fs.readdir(path) to list directory contents.
• Deleting Files and Directories:
  • Puter.fs.unlink(filePath) for files.
  • Puter.fs.rm(path, { recursive: true }) for robustly deleting files or directories (including non-empty ones).
• Checking Existence & Metadata: Puter.fs.stat(path) provides a Stats object to check if a path is a file or directory, its size, modification time, etc. Handle ENOENT to check for non-existence.
• Error Handling: Always wrap file operations in try...catch blocks to handle potential errors like ENOENT or EACCES.

With these tools, you can now build Puter.js applications that remember user settings, store data, and provide a richer, more personalized experience.

In the next chapter, we’ll move beyond just files and explore how Puter.js manages applications and windows, giving you control over the visual presentation and lifecycle of your creations!

References

• Puter.js GitHub Repository: https://github.com/HeyPuter/puter
• MDN Web Docs - async function: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function
• MDN Web Docs - Promise: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
• Node.js File System Module (Conceptual Reference for fs APIs): https://nodejs.org/docs/latest/api/fs.html

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.