Skip to main content
The Storage system provides a unified abstraction layer for working with files and folders across different environments. Whether you’re working with local file systems, browser storage, HTTP resources, or GitHub repositories, the same interfaces and patterns apply.

​
Core Concepts

The storage system is built around three main interfaces:
  • IStorage - Represents a storage system with a root folder
  • IFolder - Represents a directory/folder in the storage system
  • IFile - Represents a file in the storage system
All storage implementations share common behaviors: 
import { IStorage } from "@minecraft/creator-tools";

// All storage types expose the same interface
const storage: IStorage = /* any storage implementation */;

// Access the root folder
const rootFolder = storage.rootFolder;

// Get files and folders
const file = await rootFolder.getFileFromRelativePath("manifest.json");
const folder = await rootFolder.getFolderFromRelativePath("scripts");

​
Storage Implementations

Minecraft Creator Tools provides several storage implementations:
ImplementationEnvironmentUse Case
NodeStorageNode.jsLocal file system access in desktop/CLI
BrowserStorageBrowserClient-side persistent storage using IndexedDB
HttpStorageBrowser/NodeRead-only access to HTTP resources
GitHubStorageBrowser/NodeRead-only access to GitHub repositories
ZipStorageBothWorking with .mcpack, .mcaddon, .zip files
StorageBothIn-memory storage for temporary data
See Storage Implementations for details on each type.

​
Async Loading Pattern

Files and folders use an async loading pattern. Content is not loaded until explicitly requested: 
// Create/get a file reference (doesn't load content)
const file = await folder.ensureFileFromRelativePath("manifest.json");

// Load the file content
await file.loadContent();

// Now content is available
if (file.content) {
  console.log(file.content);
}
This pattern enables:
  • Efficient memory usage (only load what you need)
  • Better performance for large projects
  • Progressive loading of directory structures

​
Change Tracking

Storage systems track changes and provide events for monitoring updates: 
import { IStorage, IFile } from "@minecraft/creator-tools";

const storage: IStorage = /* ... */;

// Listen for file additions
storage.onFileAdded.subscribe((storage, file: IFile) => {
  console.log("File added:", file.name);
});

// Listen for file updates
storage.onFileContentsUpdated.subscribe((storage, event) => {
  console.log("File updated:", event.file.name);
});

// Listen for file removals
storage.onFileRemoved.subscribe((storage, path: string) => {
  console.log("File removed:", path);
});

​
Version History

The storage system maintains version history for files, enabling undo/redo functionality: 
import { IStorage } from "@minecraft/creator-tools";

const storage: IStorage = /* ... */;

// Access prior versions
const versions = storage.priorVersions;

// Restore to a previous version
storage.setToVersion(versionId);

// Trim versions after a specific point
storage.trimAfterVersion(versionId);

​
Error Handling

Storage operations may fail. Check for error status: 
import { IStorage, StorageErrorStatus } from "@minecraft/creator-tools";

const storage: IStorage = /* ... */;

// Check if storage is available
const available = await storage.getAvailable();

if (!available) {
  console.error("Storage not available");
}

// Check for errors
if (storage.errorStatus === StorageErrorStatus.unprocessable) {
  console.error("Storage error:", storage.errorMessage);
}

​
Common Patterns

​
Working with JSON Files

import { StorageUtilities } from "@minecraft/creator-tools";

const file = await folder.ensureFileFromRelativePath("manifest.json");
await file.loadContent();

const jsonObject = StorageUtilities.getJsonObject(file);
if (jsonObject) {
  console.log(jsonObject);
}

​
Iterating Through All Files

for await (const file of folder.allFiles) {
  await file.loadContent();
  console.log(file.name, file.content?.length);
}

​
Syncing Folders

import { StorageUtilities } from "@minecraft/creator-tools";

// Sync source folder to target folder
const modifiedCount = await StorageUtilities.syncFolderTo(
  sourceFolder,
  targetFolder,
  false, // forceFolders
  false, // forceFileUpdates
  false  // removeOnTarget
);

console.log(`${modifiedCount} files modified`);

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us