Deploying with Permaweb-Deploy

Permaweb-deploy is the recommended CLI tool for hosting decentralised applications on AR.IO Network.

It streamlines the entire deployment process by uploading your build folder to Arweave, creating Arweave manifests, and automatically updating your ArNS records in a single command.

Built on the Turbo SDK, permaweb-deploy offers flexible payment options including pre-funded Turbo Credits or on-demand topups using ARIO or Base-ETH tokens. It works seamlessly with both Arweave and EVM wallets, making it easy to integrate permanent hosting into your existing development workflow.

Prerequisites

Before starting, ensure you have:

• Node.js 18+ - Download from nodejs.org
• Arweave or EVM Wallet - You'll need the private key or JWK file
• ArNS Name - Register one at arns.app
• Command Line Familiarity - Basic terminal/shell knowledge

Project Setup

Let's create a new web application and configure it for deployment. Permaweb-deploy works with any framework that generates a static build folder.

npx create-next-app@latest my-permaweb-app
cd my-permaweb-app

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    unoptimized: true,
  },
  trailingSlash: true,
}

module.exports = nextConfig

npm install --save-dev permaweb-deploy

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "deploy": "next build && permaweb-deploy deploy --arns-name your-arns-name --deploy-folder out"
  }
}

npm create vite@latest my-permaweb-app -- --template react
cd my-permaweb-app
npm install

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: './', // Use relative paths for Arweave
})

npm install --save-dev permaweb-deploy

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "deploy": "vite build && permaweb-deploy deploy --arns-name your-arns-name"
  }
}

Deploying from the Command Line

For this walkthrough, we'll deploy directly from the command line using inline credentials. For production apps, we recommend using GitHub Actions with secrets (covered later in this guide).

DEPLOY_KEY=$(base64 -i wallet.json) npm run deploy

DEPLOY_KEY="0x1234567890abcdef..." npm run deploy

-------------------- DEPLOY DETAILS --------------------
Tx ID: abc123def456ghi789jkl012mno345pqr678stu901v
ArNS Name: your-arns-name
Undername: @
ANT: xyz789abc012def345ghi678jkl901mno234pqr567s
AR IO Process: bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM
TTL Seconds: 60
--------------------------------------------------------
Deployed TxId [abc123def456ghi789jkl012mno345pqr678stu901v] to name [your-arns-name] for ANT [xyz789abc012def345ghi678jkl901mno234pqr567s] using undername [@]

On-Demand Payment

Instead of pre-funding Turbo Credits, you can pay for deployments on-demand. Permaweb-deploy will automatically convert tokens to credits as needed.

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "deploy": "next build && permaweb-deploy deploy --arns-name your-arns-name --deploy-folder out",
    "deploy:on-demand": "next build && permaweb-deploy deploy --arns-name your-arns-name --deploy-folder out --on-demand ario --max-token-amount 2.0"
  }
}

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "deploy": "next build && permaweb-deploy deploy --arns-name your-arns-name --deploy-folder out --sig-type ethereum",
    "deploy:on-demand": "next build && permaweb-deploy deploy --arns-name your-arns-name --deploy-folder out --sig-type ethereum --on-demand base-eth --max-token-amount 0.01"
  }
}

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "deploy": "vite build && permaweb-deploy deploy --arns-name your-arns-name",
    "deploy:on-demand": "vite build && permaweb-deploy deploy --arns-name your-arns-name --on-demand ario --max-token-amount 2.0"
  }
}

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "deploy": "vite build && permaweb-deploy deploy --arns-name your-arns-name --sig-type ethereum",
    "deploy:on-demand": "vite build && permaweb-deploy deploy --arns-name your-arns-name --sig-type ethereum --on-demand base-eth --max-token-amount 0.01"
  }
}

DEPLOY_KEY=$(base64 -i wallet.json) npm run deploy:on-demand

DEPLOY_KEY="0x1234567890abcdef..." npm run deploy:on-demand

The on-demand approach is ideal for:

• Frequent deployments where pre-funding isn't convenient
• CI/CD pipelines that need reliable automated deployments
• Multi-team projects where different wallets handle different apps

Automating with GitHub Actions

Automate deployments on every push to your main branch using GitHub Actions.

name: Deploy to Arweave

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Deploy to Arweave
        run: npm run deploy
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}

{
  "scripts": {
    "deploy": "next build && permaweb-deploy deploy --arns-name myapp --deploy-folder out"
  }
}

{
  "scripts": {
    "deploy": "vite build && permaweb-deploy deploy --arns-name myapp"
  }
}

{
  "scripts": {
    "deploy": "vite build && permaweb-deploy deploy --arns-name myapp --on-demand ario --max-token-amount 2.0"
  }
}

git add .
git commit -m "Set up automated deployments"
git push origin main

Summary

You now know how to deploy permanent web applications using permaweb-deploy:

• Static site setup for Next.js and React + Vite with proper configuration
• Flexible wallet options supporting both Arweave (JWK) and EVM wallets
• Payment methods including pre-funded Turbo Credits and on-demand topups with ARIO or Base-ETH
• Command-line deployment with inline wallet credentials for quick deployments
• GitHub Actions automation for continuous deployment on every push

In the next guide, you'll learn how to use undernames to manage multiple environments and versions of your application.