Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Migrate from Pinata

A step-by-step guide to migrate your application from Pinata SDK to Pinner.

Why Migrate?

  • ✅ Privacy-focused infrastructure - Your data, your control
  • ✅ Competitive pricing - Better value for your storage needs
  • ✅ Multi-Network Access - Support for multiple storage networks through one service
  • ✅ Drop-in compatibility - Minimal code changes required

Migration Strategy

Pinner offers two approaches:

ApproachBest ForEffort
Pinata AdapterQuick migration, minimal changesLow
Native Pinner APILong-term projects, better featuresMedium

Quick Migration (Using Adapter)

Step 1: Install Pinner

SDK Installation

pnpm

pnpm add @lumeweb/pinner

npm

npm install @lumeweb/pinner

yarn

yarn add @lumeweb/pinner

Step 2: Configure Adapter

Choose the appropriate adapter and configure it. See Pinata Adapter Reference for detailed setup instructions.

For Pinata SDK 2.x: 
import { pinataAdapter } from "@lumeweb/pinner";
For Pinata SDK 1.x: 
import { pinataLegacyAdapter } from "@lumeweb/pinner";

Step 3: Replace Initialization

Replace your Pinata SDK initialization with the Pinner adapter. See Adapter Quick Setup for detailed examples.

The adapter provides the same API as Pinata SDK. See the API Comparison for a complete mapping.

See Code Examples for comprehensive side-by-side code comparisons.

Migration Checklist

  • Install @lumeweb/pinner package
  • Update imports and initialization
  • Replace API calls with adapter calls
  • Add .execute() to builder methods (v2 adapter)
  • Test file uploads
  • Test file listing and deletion
  • Update error handling (see Code Examples)
  • Remove Pinata SDK dependency
  • Deploy and monitor

Common Patterns

See Code Examples for comprehensive side-by-side comparisons of:

  • File uploads
  • Directory uploads
  • JSON uploads
  • Base64 uploads
  • Pinning by CID
  • Listing files
  • Deleting files
  • And more

Handling Differences

Builder Pattern (v2 Adapter)

The v2 adapter uses a builder pattern. Chain methods and call .execute(). See Builder Patterns for detailed examples.

Error Handling

Pinner errors follow a different structure. See Error Handling Examples.

Unsupported Features

Some Pinata features are not supported. See Unsupported Features for details and alternatives.

Testing Your Migration

  1. Test in development - Verify all upload operations work
  2. Check file listings - Ensure metadata is preserved
  3. Verify deletions - Test unpin operations
  4. Monitor performance - Compare upload speeds
  5. Check costs - Review your billing

Next Steps