Node SDK quickstart

Start here when your code runs in Node.js. You will create a small TypeScript project, generate a disposable development key, and write and read back one record.

Prerequisites

Node.js 20 or newer
Network access to https://node.tinycloud.xyz

The generated key is for this tutorial only. Never put a production wallet key in source control, logs, frontend code, or a shared .env file.

Create the project

mkdir tinycloud-node-quickstart
cd tinycloud-node-quickstart
npm init -y
npm install @tinycloud/[email protected] dotenv
npm install --save-dev tsx typescript @types/node
npm pkg set scripts.start="tsx index.ts"

Generate a new key for the empty tutorial space and exclude it from Git:

node -e "const c=require('node:crypto'),f=require('node:fs');f.writeFileSync('.env','WALLET_PRIVATE_KEY='+c.randomBytes(32).toString('hex')+'\n')"
node -e "require('node:fs').writeFileSync('.gitignore','.env\nnode_modules/\n')"

Create index.ts:

import 'dotenv/config';
import { TinyCloudNode } from '@tinycloud/node-sdk';

const privateKey = process.env.WALLET_PRIVATE_KEY;
if (!privateKey) throw new Error('WALLET_PRIVATE_KEY is missing from .env');

async function main() {
  const tc = new TinyCloudNode({
    privateKey,
    host: 'https://node.tinycloud.xyz',
    prefix: 'tinycloud-quickstart',
    autoCreateSpace: true,
  });

  await tc.signIn();

  const saved = await tc.kv.put('first-record', {
    message: 'Hello from TinyCloud',
    writtenAt: new Date().toISOString(),
  });
  if (!saved.ok) throw new Error(`${saved.error.code}: ${saved.error.message}`);

  const loaded = await tc.kv.get<{ message: string }>('first-record');
  if (!loaded.ok) throw new Error(`${loaded.error.code}: ${loaded.error.message}`);

  console.log(JSON.stringify({
    ownerDid: tc.did,
    space: tc.spaceId,
    record: loaded.data.data,
  }, null, 2));
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Run and verify

npm start

Success prints the owner DID, a space ending in :tinycloud-quickstart, and the record read back from that space:

{
  "ownerDid": "did:pkh:eip155:1:0x…",
  "space": "tinycloud:pkh:eip155:1:0x…:tinycloud-quickstart",
  "record": {
    "message": "Hello from TinyCloud"
  }
}

The exact chain, address, and timestamp will differ. A failed sign-in throws before the write. A failed KV call prints its SDK error code and exits without reporting success.

Use an existing secret safely

For a real service, replace the disposable .env key with your secret manager’s runtime injection. Keep .env for local development only, retain it in .gitignore, and use a wallet dedicated to the service rather than a personal wallet that holds assets.

Next steps

Verified against @tinycloud/node-sdk 2.7.0.

Quickstarts

Authentication and data

Collaboration and extensions

Node SDK quickstart

Prerequisites

Create the project

Run and verify

Use an existing secret safely

Next steps

​Prerequisites

​Create the project

​Run and verify

​Use an existing secret safely

​Next steps

Prerequisites

Create the project

Run and verify

Use an existing secret safely

Next steps