Filesystem API

The Filesystem API gives your resource a private, sandboxed directory for storing files. All paths are relative to your resource’s data directory — you cannot access files outside it.

Capability required: fs:resource

Frontend (iframe)

import { createResourceClient } from "@rightplace/sdk";

const rp = createResourceClient();
await rp.ready();

// Write a file
await rp.fs.writeFile("config.json", JSON.stringify({ theme: "dark" }));

// Read a file
const content = await rp.fs.readFile("config.json");
const config = JSON.parse(content);

// Check if a file exists
const exists = await rp.fs.exists("config.json");

// Create a directory
await rp.fs.mkdir("exports/2026");

// List directory contents
const entries = await rp.fs.readDir("exports");
// → [{ name: "2026", type: "dir", size: 0 }]

// Get file info
const info = await rp.fs.stat("config.json");
// → { size: 24, type: "file", created: 1713250000000, modified: 1713250000000 }

// Copy and move
await rp.fs.copy("config.json", "config.backup.json");
await rp.fs.move("old-name.txt", "new-name.txt");

// Delete
await rp.fs.delete("config.backup.json");
await rp.fs.delete("exports"); // deletes directory recursively

Backend (Node.js)

import { createResourceServer } from "@rightplace/sdk/server";

const server = createResourceServer({
  methods: {
    exportData: async (params, { rp }) => {
      const data = JSON.stringify(params.data, null, 2);
      await rp.fs.mkdir("exports");
      await rp.fs.writeFile(`exports/${params.filename}`, data);
      return { ok: true };
    },
    
    listExports: async (_params, { rp }) => {
      const exists = await rp.fs.exists("exports");
      if (!exists) return [];
      return rp.fs.readDir("exports");
    },
  },
});

server.start();

API Reference

rp.fs.readFile(path)

Read a file as UTF-8 text.

Parameter	Type	Description
path	string	Relative path to the file
Returns	Promise<string>	File contents as text

rp.fs.readFileBase64(path)

Read a file as base64-encoded binary.

Parameter	Type	Description
path	string	Relative path to the file
Returns	Promise<string>	File contents as base64

rp.fs.writeFile(path, content)

Write text content to a file. Creates parent directories automatically.

Parameter	Type	Description
path	string	Relative path to the file
content	string	Text content to write

rp.fs.writeFileBase64(path, content)

Write binary content from a base64 string. Creates parent directories automatically.

Parameter	Type	Description
path	string	Relative path to the file
content	string	Base64-encoded content

rp.fs.mkdir(path)

Create a directory (and any missing parent directories).

Parameter	Type	Description
path	string	Relative path to create

rp.fs.readDir(path)

List the contents of a directory.

Parameter	Type	Description
path	string	Relative directory path
Returns	Promise<FsDirEntry[]>	Array of entries

Each entry: { name: string, type: "file" | "dir", size: number }

rp.fs.delete(path)

Delete a file or directory (recursive for directories).

Parameter	Type	Description
path	string	Relative path to delete

rp.fs.move(from, to)

Move or rename a file or directory.

Parameter	Type	Description
from	string	Source relative path
to	string	Destination relative path

rp.fs.copy(from, to)

Copy a file.

Parameter	Type	Description
from	string	Source relative path
to	string	Destination relative path

rp.fs.exists(path)

Check if a file or directory exists.

Parameter	Type	Description
path	string	Relative path to check
Returns	Promise<boolean>

rp.fs.stat(path)

Get file or directory metadata.

Parameter	Type	Description
path	string	Relative path
Returns	Promise<FsStatResult>	Metadata object

Returns: { size: number, type: "file" | "dir", created: number, modified: number }

Timestamps are milliseconds since Unix epoch.

Path Rules

• All paths are relative to your resource’s data directory
• No ../ — path traversal is rejected
• No absolute paths — /etc/passwd is rejected
• Parent directories are created automatically for write operations
• Paths use forward slashes (/) on all platforms

Manifest Configuration

{
  "capabilities": [
    "fs:resource"
  ]
}

Storage Location

Files are stored at:

~/.rightplace/{user_id}/resources/{manifest_id}/data/

This directory is created automatically on first use. Files persist across app restarts and resource updates. Files are deleted when the resource is uninstalled.