IPFS Pinning Tutorial: Build a Filecoin dApp That Never Loses Your Files

• IPFS pinning tells your node to keep a file forever — without it, files can vanish during routine cleanup called garbage collection.
• There are three ways to pin: locally on your own node, through a desktop app, or using a remote service like Pinata.
• Filecoin adds economic incentives on top of IPFS, turning “someone might keep this” into “storage providers are paid to keep this.”
• Every pinned file gets a unique Content Identifier (CID) — like a fingerprint tied to the file’s contents, not a server address.
• You can build a working dApp that pins files to Filecoin with just a few lines of JavaScript and a free Pinata account.
• Chia miners already understand this model — your plot files on disk are your contribution to the network, just like storage providers on Filecoin.

An IPFS pinning tutorial teaches you how to make sure files your dApp uploads actually stay online. Without pinning, IPFS treats your files like a browser cache — useful for a while, then deleted. This guide walks you through every method, from the command line to a full JavaScript dApp with Filecoin-backed storage, one line of code at a time.

What Is IPFS Pinning? (And Why Your dApp Needs It Right Now)

Imagine you put a sticky note on your desk. Without the sticky part, it blows away. Pinning in IPFS is that sticky part. When you add a file to IPFS, the network gives it a Content Identifier (CID) — a hash fingerprint based on what the file contains, not where it is stored. Your local node will hold onto that file for a while, but IPFS runs a process called garbage collection that sweeps away files that are not marked as important. Pinning is how you mark a file as important.

This matters a lot for dApp builders. If your app uploads a user’s profile image or an NFT’s metadata to IPFS without pinning it, that file could disappear within hours — right after the user paid to mint. That is not a good experience. Pinning solves this by telling one or more IPFS nodes: “Never delete this CID.”

Content Addressing vs. Location Addressing

Traditional web servers use location-based addresses. Your file lives at a URL like https://myserver.com/profile.jpg. If the server goes down, the link breaks. IPFS does something different. Every file gets an address based on its content. Change even one character in the file and you get a completely different CID. This means the same file has the same address on every node in the world, forever. No broken links, no single point of failure, and no trusting a company to keep the lights on.

For crypto miners switching to dApp development, this will feel familiar. On Chia Network, coins are addressed by their puzzle hash — a cryptographic identifier tied to the spending rules, not to a server location. IPFS CIDs work on the same principle: the identifier is generated from the content itself, making it tamper-proof and verifiable without a central authority. If you’ve already wrapped your head around Chialisp puzzles, content addressing is one less concept to learn from scratch.

What Garbage Collection Means for Your dApp

IPFS garbage collection is not a bug — it’s by design. Nodes have limited disk space, so IPFS automatically removes unpinned files to free room. On a local development node, this can happen every few hours. On a remote node or cloud VM, it can happen even faster. The moment garbage collection runs and your user’s file is not pinned, it is gone from that node. Other nodes might still have it if it was popular enough to be requested and cached, but you cannot count on that. Pinning is the only reliable way to guarantee a CID stays retrievable for your users.

The Three IPFS Pinning Methods: Which One Fits Your Build?

There is not one single way to pin in IPFS. The right method depends on your setup — whether you are running your own node, prefer a graphical interface, or want cloud-level availability without managing servers yourself. Here is a plain-English breakdown of all three, followed by a quick decision table.

Method 1 — Local Pinning with the Kubo CLI

Kubo is the most popular IPFS implementation and runs entirely from your terminal. If you are already comfortable with a command line — which most miners are — this method is the fastest to get started with. When you run ipfs add, the file is automatically pinned to your local node. But you can also pin CIDs that already exist on the network without re-uploading them.

Here are the four commands you will use most often:

# Add a file to your node AND pin it at the same time
ipfs add myfile.png
# The terminal will print a CID like: QmXoypizjW3...

# Pin a CID that already lives on the IPFS network to your node
ipfs pin add <CID>

# See a list of everything you have pinned
ipfs pin ls --type=all

# Remove a pin (lets garbage collection delete it later)
ipfs pin rm <CID>

Local pinning works great during development. The downside is that your files are only available when your computer is on and connected to the internet. If you close your laptop, your node goes offline and users cannot reach your files. That is where remote pinning steps in.

Method 2 — IPFS Desktop GUI

IPFS Desktop is a free application that bundles a Kubo node with a point-and-click interface. It is a great starting point if you prefer not to type commands. Once installed, you open the Files screen, click Import to upload a file, then right-click the file and choose Set pinning. The app handles the rest. You can also configure remote pinning services directly inside the app through the Settings screen under Pinning Services. This means you can pin locally and remotely at the same time with a few clicks — useful for redundancy.

Method 3 — Remote Pinning Service (Pinata, Filebase, Storacha)

Remote pinning services run IPFS nodes for you, 24 hours a day, 7 days a week. Your computer can be turned off and your files stay online. Services like Pinata, Filebase, and Storacha all follow the IPFS Pinning Service API standard, which means you can add them to Kubo or IPFS Desktop using the same commands regardless of which service you pick. This is the approach most dApp builders use in production.

Quick Decision Table: Choosing Your IPFS Pinning Method

IPFS Pinning Tutorial: Build a dApp with Node.js and Pinata

This section builds a real, working file-upload dApp that pins to IPFS via Pinata and stores the CID in your app’s output. Every line of code is explained so you know exactly what is happening. You need Node.js installed on your machine and a free Pinata account to follow along.

Step 1 — Create a Free Pinata Account and Get Your API Key

Go to pinata.cloud and sign up for a free account. Pinata’s free tier gives you 1 GB of storage and unlimited pins to start — enough to build and test a real dApp. After signing in, go to your profile menu and click API Keys. Create a new key with Admin permissions, give it a name like “my-dapp-key,” and save both values shown: your API Key and your API Secret. You will use these in your code. Never commit them to a public GitHub repository — always store them in environment variables.

Step 2 — Set Up Your Node.js Project

Open a terminal in a new folder and run the following commands one at a time:

# Create a new project folder and enter it
mkdir ipfs-pin-dapp
cd ipfs-pin-dapp

# Initialize a Node.js project (accept all defaults)
npm init -y

# Install Pinata's official SDK and dotenv for environment variables
npm install pinata dotenv

# Create your environment file — NEVER commit this to GitHub
touch .env

Open the .env file you just created and add your keys like this, replacing the placeholder text with your actual values from the Pinata dashboard:

PINATA_API_KEY=your_api_key_here
PINATA_API_SECRET=your_api_secret_here

Step 3 — Write the Pin Script

Create a file called pin.js in your project folder. Paste the code below. Every line has a comment explaining what it does:

// Load environment variables from our .env file
require('dotenv').config();

// Import the file system module — built into Node.js, no install needed
const fs = require('fs');

// Import FormData to package our file for the HTTP request
const FormData = require('form-data');

// Import axios — a simple tool for making HTTP requests
const axios = require('axios');

// Pull our API keys out of the environment variables
const PINATA_API_KEY = process.env.PINATA_API_KEY;
const PINATA_API_SECRET = process.env.PINATA_API_SECRET;

// Define our main async function — async lets us use "await" inside it
async function pinFileToPinata(filePath) {

  // Create a new FormData object — this is how we send a file over HTTP
  const formData = new FormData();

  // Attach our file to the FormData. fs.createReadStream reads the file
  // without loading the whole thing into memory at once
  formData.append('file', fs.createReadStream(filePath));

  try {
    // Send a POST request to Pinata's API endpoint for file pinning
    const response = await axios.post(
      '//api.pinata.cloud/pinning/pinFileToIPFS',
      formData,
      {
        // Set the headers so Pinata knows who we are
        headers: {
          'pinata_api_key': PINATA_API_KEY,
          'pinata_secret_api_key': PINATA_API_SECRET,
          // FormData generates a special boundary string for multipart uploads
          ...formData.getHeaders()
        }
      }
    );

    // If the request worked, Pinata returns the CID in response.data.IpfsHash
    console.log('File pinned successfully!');
    console.log('Your CID is:', response.data.IpfsHash);

    // Build a public gateway URL so anyone can view the file in a browser
    const gatewayUrl = `//gateway.pinata.cloud/ipfs/${response.data.IpfsHash}`;
    console.log('View your file here:', gatewayUrl);

  } catch (error) {
    // If something went wrong, print the error message
    console.error('Pinning failed:', error.message);
  }
}

// Call our function with a test file path — change this to your file
pinFileToPinata('./test.txt');

Install the one missing library that FormData needs in some environments:

# axios might already be installed — this just makes sure
npm install axios form-data

Step 4 — Create a Test File and Run the Script

Create a simple test file to upload:

# Create a small text file to test with
echo "Hello from my Filecoin dApp!" > test.txt

# Run the pin script
node pin.js

If everything is set up correctly, your terminal will print a CID and a gateway URL. Open that URL in a browser and you will see your test file hosted on IPFS, pinned through Pinata’s infrastructure. That file will stay online as long as your free Pinata account is active — no servers to manage, no uptime to worry about on your end.

Step 5 — Add a Second Pin to Filecoin for Long-Term Storage

Pinata alone keeps your file available through their service. To go further and back it with Filecoin’s cryptographic storage proofs, you can use Lighthouse or Filecoin Pin — newer tools that make Filecoin deals alongside IPFS pinning. Lighthouse wraps both steps: upload once, get an IPFS CID, and an automatic Filecoin storage deal in the background.

# Install the Lighthouse SDK
npm install @lighthouse-web3/sdk

# Then in your code, swap pinata's upload call for Lighthouse's:
const lighthouse = require('@lighthouse-web3/sdk');
const response = await lighthouse.upload('./test.txt', 'YOUR_LIGHTHOUSE_API_KEY');
console.log('CID:', response.data.Hash);
// Lighthouse automatically creates a Filecoin deal for this CID

Your file is now pinned to IPFS for fast retrieval AND stored on the Filecoin network with cryptographic proof that storage providers are holding it. This is the gold standard for dApp data storage in 2025.

Filecoin vs. IPFS-Only Pinning: Side-by-Side Comparison

How IPFS Pinning Connects to Chia and Chialisp

If you came from Chia farming, this whole system probably feels familiar in ways you did not expect. On Chia, your hard drive plots are your contribution to the network. You store data, and when you win a block, you earn XCH. Filecoin storage providers do almost the same thing: they dedicate disk space to holding user files, and the Filecoin network pays them FIL for proving they are still holding that data. Both models replace energy-hungry computation with useful storage work.

The connection goes deeper on the development side too. Chialisp, Chia’s smart contract language, addresses coins by their puzzle hash — a cryptographic fingerprint of the spending rules, not a server location. IPFS addresses files by their CID — a cryptographic fingerprint of the file content, not a server location. Both reject the idea that you should have to trust a company’s URL to stay working. If you have already built with Chialisp smart contracts, you understand content addressing at a conceptual level — you just used different terminology.

Chia’s DataLayer takes this one step further. It is a decentralized key-value store where off-chain data is referenced by on-chain Chialisp coin commitments. A dApp built on Chia can store a file’s IPFS CID inside a DataLayer record, then have a Chialisp puzzle verify that the CID has not changed before allowing a coin spend. This creates a bridge between IPFS storage and Chia’s on-chain logic — a pattern that is still underexplored and represents a real opportunity for developers coming from the Chia farming community.

“IPFS provides a high throughput content-addressed block storage model, with content-addressed hyperlinks. This forms a generalized Merkle DAG, a data structure upon which one can build versioned file systems, blockchains, and even a Permanent Web.”

— Juan Benet, Founder of Protocol Labs and Creator of IPFS, IPFS: Content Addressed, Versioned, P2P File System, arXiv, 2014

Real-World Case: NFT Metadata That Stays Alive

One of the clearest real-world uses of IPFS pinning is NFT metadata storage. When an NFT is minted on any blockchain, the smart contract typically stores a tokenURI — a link to a JSON file describing the NFT’s image, name, and traits. If that link points to a central server, the server can go down, the company can shut down, or the URL can change. Dozens of early NFT collections discovered this the hard way when their metadata disappeared, leaving collectors with tokens pointing to nothing. Projects that pinned their metadata to IPFS — and backed it with Filecoin storage deals — have metadata that remains accessible regardless of what happens to the original team or company.

Start Pinning: Your Files Deserve Better Than a Temporary Cache

An IPFS pinning tutorial is not just about learning commands — it is about understanding why decentralized storage matters and how to build apps that do not let users down. You have seen three pinning methods, walked through a working Node.js script that uploads and pins files to Filecoin via Pinata, and learned how Filecoin’s storage proofs take availability to the next level. For miners already familiar with plot storage and proof of space, the mental model is closer than you think. The next step is yours: grab a free Pinata account, run the script above, and start building a dApp where your users’ data actually sticks around.

IPFS Pinning Tutorial FAQs

What is an IPFS pinning tutorial and why do I need one as a dApp developer?

An IPFS pinning tutorial teaches you how to mark files so they are never deleted from an IPFS node during garbage collection. As a dApp developer, you need this because any file you upload without pinning — user images, NFT metadata, app assets — can disappear within hours, breaking your application for real users.

What happens to my IPFS files if I don’t pin them?

Unpinned IPFS files are treated as temporary cache and removed automatically during garbage collection, which can run as often as every few hours on a busy node. Once garbage collected from the last node holding it, the file becomes unreachable on the network unless another node has cached a copy — which you cannot rely on.

Is this IPFS pinning tutorial compatible with Filecoin storage?

Yes — this IPFS pinning tutorial covers both standalone IPFS pinning through Pinata and Filecoin-backed storage through services like Lighthouse, which handles the Filecoin storage deal automatically in the background when you upload a file.

What is the difference between a recursive pin and a direct pin in IPFS?

A recursive pin pins a CID and all of its child blocks — this is the default behavior when you run ipfs add and is what you want for most files and folders. A direct pin only pins the specific block you name and ignores any linked child blocks, which is rarely what dApp developers need.

Can I use IPFS pinning for free when building my first dApp?

Yes — Pinata offers a free tier with 1 GB of storage and no time limit, making it a practical option for learning and early-stage dApp development. Storacha and Filebase also offer free entry points, so you can test this IPFS pinning tutorial without spending anything upfront.

IPFS Pinning Tutorial Citations

1. IPFS Documentation — Pin a file with IPFS using a pinning service: https://docs.ipfs.tech/quickstart/pin/
2. IPFS Documentation — Pin files (local Kubo guide): https://docs.ipfs.tech/how-to/pin-files/
3. IPFS Documentation — Work with pinning services: https://docs.ipfs.tech/how-to/work-with-pinning-services/
4. IPFS Documentation — Pin using the command line: https://docs.ipfs.tech/quickstart/pin-cli/
5. Filecoin Blog — Five Years of Filecoin: What We’ve Built and What’s Next: https://filecoin.io/blog/posts/five-years-of-filecoin-what-we-ve-built-and-what-s-next/
6. Pinata Developer Docs: https://docs.pinata.cloud/
7. Juan Benet — IPFS: Content Addressed, Versioned, P2P File System (arXiv): https://arxiv.org/abs/1407.3561
8. Lighthouse Storage — What is IPFS Pinning and Complete Guide: https://www.lighthouse.storage/blogs/What%20is%20IPFS%20Pinning
9. GitHub — Filecoin Pin Demo dApp: https://github.com/filecoin-project/filecoin-pin-website
10. ChiaTribe — Chialisp: Transforming Blockchain with Next-Gen Smart Contracts: https://chiatribe.com/chialisp-transforming-blockchain-unlocking-next-gen-smart-contracts/