Documentation Index
Fetch the complete documentation index at: https://mintlify.com/mojang/minecraft-creator-tools/llms.txt
Use this file to discover all available pages before exploring further.
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:
| Implementation | Environment | Use Case |
|---|
| NodeStorage | Node.js | Local file system access in desktop/CLI |
| BrowserStorage | Browser | Client-side persistent storage using IndexedDB |
| HttpStorage | Browser/Node | Read-only access to HTTP resources |
| GitHubStorage | Browser/Node | Read-only access to GitHub repositories |
| ZipStorage | Both | Working with .mcpack, .mcaddon, .zip files |
| Storage | Both | In-memory storage for temporary data |
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);
}
- 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