Deploying with ARIO Deploy

ARIO Deploy is the recommended CLI tool for hosting decentralised applications on ar.io.

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, ario-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
• Upload Wallet - An Arweave JWK or EVM private key to pay for the upload
• Solana Wallet - A base58 Solana secret key that controls your ArNS name (for ArNS record updates)
• ArNS Name - Register one at arns.ar.io
• Command Line Familiarity - Basic terminal/shell knowledge

Project Setup

Let's create a new web application and configure it for deployment. ARIO 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 @ar.io/deploy

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "deploy": "next build && ario-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 @ar.io/deploy

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "deploy": "vite build && ario-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) ARNS_KEY="your-base58-solana-key" npm run deploy

DEPLOY_KEY="0x1234567890abcdef..." ARNS_KEY="your-base58-solana-key" npm run deploy

Starting deployment...

✔ ARIO initialized
✔ ArNS record fetched for your-arns-name
✔ Signer created (arweave)
✔ Turbo initialized
✔ Upload planned: 12 of 48 files to upload (1.2 MiB), 36 cached, 0 duplicates
✔ Turbo credits check passed
✔ Folder uploaded: abc123def456ghi789jkl012mno345pqr678stu901v (36/48 files cached, 12 uploaded) (files cached for future uploads)
✔ ANT record updated

Deployment Successful!
┌─────────────┬───────────────────────────────────────────────┐
│ Tx ID       │ abc123def456ghi789jkl012mno345pqr678stu901v  │
│ ArNS Name   │ your-arns-name                               │
│ Undername   │ @                                             │
│ ArNS URL    │ https://your-arns-name.ar.io                  │
└─────────────┴───────────────────────────────────────────────┘

Reducing Upload Costs

Arweave storage is paid per byte, once. Three features keep redeploys cheap:

• Deduplication (on by default). ario-deploy hashes every file and keeps a local cache (.ario-deploy/transaction-cache.json) of what it has already uploaded. Unchanged files reuse their existing transaction instead of being uploaded again, and files that are identical to another file in the same deploy are uploaded once. The credit check prices only what will actually be uploaded.
• Incremental uploads (opt-in). --incremental tags each file with its content hash, and later deploys look your wallet's past uploads up on chain. A machine with no local cache, such as a fresh CI runner, still pays only for the files that changed. Uploads take a few minutes (about 5-7 in our measurements) to become findable, so a redeploy seconds after the last one may upload some files again.
• Compression (opt-in). --compress gzip compresses each file before upload and tags it with Content-Encoding, so gateways serve it with that header and browsers decompress it transparently. HTML, JavaScript, CSS and JSON typically shrink 5-8x; already-compressed formats (JPEG, PNG, GIF, WebP, AVIF, WOFF/WOFF2, MP3, MP4, WebM, and archives) are uploaded as-is.

{
  "scripts": {
    "deploy": "next build && ario-deploy deploy --arns-name your-arns-name --deploy-folder out --incremental --compress gzip --compress-exclude \"llms*.txt,*.md\""
  }
}

--compress-exclude keeps files uncompressed that tools fetch with plain HTTP clients such as curl, which do not decode gzip unless asked to.

Measured on a 1,229-file static docs site with both flags: a redeploy from a fresh CI runner with no local cache found 1,228 files on chain and uploaded one (2.5 MiB), where the first deploy uploaded 33 MiB. Turning compression or incremental uploads on for the first time uploads each file once more, because those uploads are tracked separately.

On-Demand Payment

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

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "deploy": "next build && ario-deploy deploy --arns-name your-arns-name --deploy-folder out",
    "deploy:on-demand": "next build && ario-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 && ario-deploy deploy --arns-name your-arns-name --deploy-folder out --sig-type ethereum",
    "deploy:on-demand": "next build && ario-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 && ario-deploy deploy --arns-name your-arns-name",
    "deploy:on-demand": "vite build && ario-deploy deploy --arns-name your-arns-name --on-demand ario --max-token-amount 2.0"
  }
}

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "deploy": "vite build && ario-deploy deploy --arns-name your-arns-name --sig-type ethereum",
    "deploy:on-demand": "vite build && ario-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) ARNS_KEY="your-base58-solana-key" npm run deploy:on-demand

DEPLOY_KEY="0x1234567890abcdef..." ARNS_KEY="your-base58-solana-key" 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

The simplest way to automate deployments is with the official ar-io/ar-io-deploy GitHub Action. It handles node setup, dedup caching, and PR preview comments automatically.

name: Deploy to Arweave

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

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

      - name: Install and build
        run: |
          npm ci
          npm run build

      - name: Deploy to Arweave
        uses: ar-io/ar-io-deploy@v1
        with:
          deploy-key: ${{ secrets.DEPLOY_KEY }}
          arns-key: ${{ secrets.ARNS_KEY }}
          arns-name: ${{ secrets.ARNS_NAME }}
          # Optional (see Reducing Upload Costs). incremental needs v1.2.0+ and
          # compress v1.1.0+; pin that version, since the floating v1 tag may lag.
          # incremental: 'true'
          # compress: gzip
          # compress-exclude: 'llms*.txt,*.md'

name: PR Preview

on:
  pull_request:
    types: [opened, synchronize, reopened, closed]

jobs:
  preview:
    runs-on: ubuntu-latest
    if: github.event.pull_request.head.repo.full_name == github.repository

    steps:
      - uses: actions/checkout@v4

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

      - name: Install and build
        run: |
          npm ci
          npm run build

      - name: Deploy preview
        uses: ar-io/ar-io-deploy@v1
        with:
          deploy-key: ${{ secrets.DEPLOY_KEY }}
          arns-key: ${{ secrets.ARNS_KEY }}
          arns-name: ${{ secrets.ARNS_NAME }}
          preview: 'true'
          github-token: ${{ secrets.GITHUB_TOKEN }}

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

Summary

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

• Static site setup for Next.js and React + Vite with proper configuration
• Two-key model with separate upload (DEPLOY_KEY) and ArNS authority (ARNS_KEY) keys
• Flexible wallet options supporting Arweave, EVM, and Solana wallets
• Payment methods including pre-funded Turbo Credits and on-demand topups with ARIO or Base-ETH
• Lower upload costs through automatic deduplication, optional incremental uploads, and optional gzip compression
• Command-line deployment with inline wallet credentials for quick deployments
• GitHub Actions automation with the official ar-io/ar-io-deploy action for production deploys and PR previews

For more details, see the ARIO Deploy GitHub repository.

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