Getting Started

Set up the Pinner SDK and pin your first file in about five minutes.

Prerequisites

An API key: create one in your account
Node.js 20+ or a modern browser

Install the package

Initialize Pinner

The SDK needs an API key to authenticate. In a browser, pass it directly. On the server, read it from the environment.

import { Pinner } from "@lumeweb/pinner";
 
const pinner = new Pinner({
  jwt: "YOUR_JWT"
});

import { Pinner } from "@lumeweb/pinner";
 
const pinner = new Pinner({
  jwt: process.env.PINNER_AUTH_TOKEN
});

Upload your first file

uploadAndWait pins the file and waits for the pin to settle. It returns an UploadResult with the CID (may be undefined for TUS uploads until the server assigns it), name, size, and more.

const file = new File(["Hello, Pinner!"], "hello.txt", { type: "text/plain" });
const result = await pinner.uploadAndWait(file);
 
console.log("CID:", result.cid);

import { readFileSync } from "fs";
 
// Node.js 20+ provides the global File class
const buffer = readFileSync("./hello.txt");
const file = new File([buffer], "hello.txt", { type: "text/plain" });
const result = await pinner.uploadAndWait(file);
 
console.log("CID:", result.cid);

uploadAndWait handles the full cycle: it uploads the file, waits for pinning to complete, and returns an UploadResult with the CID (may be undefined for TUS uploads until the server assigns it), name, size, and more.

Verify the connection

Upload a small file and confirm you get a CID back. This proves both authentication and connectivity work end-to-end.

const file = new File(["ping"], "ping.txt", { type: "text/plain" });
const result = await pinner.uploadAndWait(file);
 
if (result.cid) {
  console.log("Connected! CID:", result.cid);
} else {
  console.log("Upload sent, operation ID:", result.id);
}

Type your config

If you prefer explicit types, import PinnerConfig:

import { Pinner, PinnerConfig } from "@lumeweb/pinner";
 
const config: PinnerConfig = {
  jwt: "YOUR_JWT",
  endpoint: "https://ipfs.pinner.xyz"
};
 
const pinner = new Pinner(config);

import { Pinner, PinnerConfig } from "@lumeweb/pinner";
 
const config: PinnerConfig = {
  jwt: process.env.PINNER_AUTH_TOKEN,
  endpoint: "https://ipfs.pinner.xyz"
};
 
const pinner = new Pinner(config);

Ready to customize? See Configuration for endpoints, gateways, storage backends, and environment-specific setup.