ZBURN Core Utilities

ZBURN Core Utilities is your essential toolkit for bridging the gap between traditional Web2 deployments and the decentralized Web3 world. This package provides robust functionalities for deploying your web projects to IPFS, ensuring persistence through distributed pinning, and making them seamlessly accessible via Cloudflare.

Whether you're looking for a one-click deployment for your CI/CD pipeline or granular control over each step, ZBURN offers the flexibility you need.

🚀 Features

• IPFS Deployment: Easily deploy your local project folders to the InterPlanetary File System (IPFS).
• Distributed Pinning: Automatically pin your content across multiple IPFS pinning services (like 4EVERLAND and your custom ZBURN gateway) to ensure high availability and persistence.
• Gateway Stimulation: Accelerate content propagation by "stimulating" various public IPFS gateways, making your content discoverable faster.
• Cloudflare Integration:
  • DNSLink Updates: Automatically update your Cloudflare _dnslink TXT records.
  • KV Namespace Updates: Update Cloudflare Workers KV Namespaces with the latest CID.
• Flexible CLI: Use a simple command-line interface for quick deployments or detailed control.
• Programmatic API: Integrate ZBURN's functionalities directly into your Node.js scripts.

📦 Installation

To get started with ZBURN, install the core package via npm:

npm install @zburn/core

⚙️ Configuration (.zburnrc.json)

ZBURN uses a .zburnrc.json file in your project's root directory to manage all your deployment settings.

{
  "pin_gateways": [
    {
      "urlTemplate": "https://api.4everland.dev/pins",
      "method": "POST",
      "auth": {
        "type": "Bearer",
        "tokenEnvVar": "EVERPIN_ACCESS_TOKEN"
      },
      "headers": {
        "Content-Type": "application/json"
      },
      "bodyTemplate": {
        "cid": "{{cid}}",
        "name": "pin-{{cid}}"
      }
    },
    {
      "urlTemplate": "https://gateway.zburn.xyz/ipfs/{{cid}}",
      "method": "GET"
    }
  ],
  "stimulate_gateways": [
    "https://w3s.link/ipfs/",
    "https://cloudflare-ipfs.com/ipfs/",
    "https://gateway.pinata.cloud/ipfs/",
    "https://dweb.link/ipfs/",
    "https://gateway.zburn.xyz/ipfs/"
  ],
  "pin_env_var": {
    "EVERPIN_ACCESS_TOKEN": "XXX"
  },
  "cloudflare": {
    "apiToken": "XXXX-XXXX-XXXX-XX",
    "accountId": "XXXX",
    "zoneId": "XXXX",
    "worker": {
      "kvNameSpace": "MY_AMAZING_KVNAMESPACE",
      "kvKey": "MY_AMAZING_KV_KEY"
    },
    "dnsLink": {
      "domain": "my-amazing-website.com",
      "subdomain": "_dnslink",
      "ttl": 300
    }
  }
}

🖥️ Usage

Command-Line Interface (CLI)

npx zburn deploy <folder>

Example:

npx zburn deploy ./dist

IPFS Only Deployment

npx zburn deploy ipfs ./build

Cloudflare Only Update

npx zburn deploy cloudflare QmYtRpU6s3t5q7k8m9n0p1q2r3s4t5u6v7w8x9y0z

Help

npx zburn help

📚 Programmatic Usage

const zburn = require('@zburn/core');

async function myCustomDeployment() {
  try {
    const cid = await zburn.ipfs.deploy('./my-project/build');
    console.log(\`Deployed to IPFS with CID: \${cid}\`);

    const finalCid = await zburn.deployFull('./another-project/dist');
    console.log(\`Full deployment completed with CID: \${finalCid}\`);
  } catch (error) {
    console.error("Deployment failed:", error);
  }
}

myCustomDeployment();

🔑 Getting Your Configuration Data

4EVERLAND Access Token (EVERPIN_ACCESS_TOKEN)

1. Go to 4everland.org and log in.
2. Generate or copy an API token.
3. Set it as an environment variable:

export EVERPIN_ACCESS_TOKEN="YOUR_TOKEN_HERE"

Cloudflare API Configuration

• Account ID and Zone ID from the Cloudflare dashboard.
• API Token: Create a custom token with permissions for DNS and Workers KV.
• Worker Script Name, KV Namespace, and KV Key from Workers dashboard.
• DNSLink setup: _dnslink.my-amazing-website.com

📘 License

MIT

If you'd like to follow ZBURN updates or just say thanks, follow us on X: https://x.com/ZBURN_X