Module @stacks/storage


Store and fetch files with Gaia, the decentralized storage system.


npm install @stacks/storage


Initiate a session

Users must authenticate to an app before the storage package will work to save or retrieve data on their behalf.

See also authentication guide using connect for web apps

The storage capabilities will work in cases userSession.isUserSignedIn() returns true

Initiating a storage client

import { UserSession, AppConfig } from '@stacks/auth';
import { Storage } from '@stacks/storage';

const privateKey = '896adae13a1bf88db0b2ec94339b62382ec6f34cd7e2ff8abae7ec271e05f9d8';
const appConfig = new AppConfig();
const userSession = new UserSession({ appConfig }); = <any> {
appPrivateKey: privateKey,
const storage = new Storage({ userSession });

Note that you can also use an existing userSession object created during the authentication process.

Put file

const myData = JSON.stringify({
hello: "world",
num: 1

const fileUrl = await storage.putFile('my_data.json', myData);
// You'll need to save an entirely new string of modified data using putFile with the same fileName every time you want to update a record.
// There is no separate update method.

Store data at a different path

const fileUrl = await storage.putFile('path/my_data.json', myData);

Put file with options

const putFileOptions = {
// override the default content type
contentType: 'application/json',
// override encrypting data by default
// you can also set encrypt to a private key to specify a custom encryption key
encrypt: false,
// ignore automatic conflict prevention using etags
dangerouslyIgnoreEtag: true

const fileUrl = await storage.putFile('my_data.json', myData, putFileOptions);

Get file

const fileContent = await storage.getFile('my_data.json');

Get file with options

const getFileOptions = {
decrypt: false,
// by default files stored are signed and can be verified for authenticity
verify: false

const fileContent = await storage.getFile('my_data.json', getFileOptions);

Get file for other user

// Retrieve public data saved by users other than the one with the active session
// User should have registered username via BNS
const options = {
username: '',
// app: '',
decrypt: false,
// Set an additional app property within options to retrieve data for a user as saved by an app hosted at a separate domain

const fileContent = await storage.getFile('my_data.json', options);

Delete file

await storage.deleteFile('my_data.json');

Delete the file and the corresponding signature file if signed

await storage.deleteFile('my_data.json', { wasSigned: true });

List file

List all files in the user's Gaia hub

const files: Promise<string | undefined | ArrayBuffer | null>[] = [];
const options = { decrypt: false };
await storage.listFiles((filename: string) => {
if (filename === 'my_data.json') {
files.push(storage.getFile(filename, options));
// return false to stop iterating through files
return false;
} else {
// return true to continue iterating
return true;
const fileContents = await Promise.all(files);





Generated using TypeDoc