diff --git a/content/build/guides/hosting-decentralised-apps/deploying-with-ario-deploy.mdx b/content/build/guides/hosting-decentralised-apps/deploying-with-ario-deploy.mdx
new file mode 100644
index 000000000..96613a2f6
--- /dev/null
+++ b/content/build/guides/hosting-decentralised-apps/deploying-with-ario-deploy.mdx
@@ -0,0 +1,611 @@
+---
+title: "Deploying with ARIO Deploy"
+description: "Learn how to deploy permanent web applications to Arweave using the @ar.io/deploy CLI tool with Next.js, React, and GitHub Actions"
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+import { Steps, Step } from 'fumadocs-ui/components/steps';
+import { Card, Cards } from 'fumadocs-ui/components/card';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+import {
+ Terminal,
+ Rocket,
+ Wallet,
+ Zap,
+ GitBranch,
+ BookOpen,
+ Bot,
+ Shield,
+} from 'lucide-react';
+
+ARIO Deploy (`@ar.io/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 optionally updating your ArNS records in a single command. Built on the Turbo SDK, it offers flexible payment options, smart deduplication, interactive mode, a first-class GitHub Action for CI/CD, and even AI-assisted deployments via Claude Code.
+
+
+ }
+ />
+ }
+ />
+ }
+ />
+ }
+ />
+
+
+
+ Check out the [series introduction](/build/guides/hosting-decentralised-apps) to learn about permanent hosting and ArNS domains.
+
+
+## Prerequisites
+
+Before starting, ensure you have:
+
+- **Node.js 18+** — Download from [nodejs.org](https://nodejs.org/)
+- **A Wallet** — Arweave (JWK), Ethereum/Polygon/KYVE (hex key), or Solana (base58 key)
+- **ArNS Name** (optional) — Register one at [arns.ar.io](https://arns.ar.io)
+- **Turbo Credits** — Fund your wallet at [console.ar.io/topup](https://console.ar.io/topup) or use on-demand payment
+
+
+ ARIO Deploy uses two separate keys:
+
+ - **`DEPLOY_KEY`** — pays for the upload. Can be any supported signer type.
+ - **`ARNS_KEY`** — updates the ArNS record. Must always be a **Solana** key that controls the ArNS name.
+
+ If you use a Solana wallet for uploads, the same key can serve both roles.
+
+
+## Installation
+
+Install `@ar.io/deploy` as a dev dependency in your project or globally:
+
+```bash title="Terminal"
+# As a dev dependency (recommended for teams)
+npm install --save-dev @ar.io/deploy
+
+# Or globally
+npm install -g @ar.io/deploy
+```
+
+The CLI command is `ario-deploy`. Verify it works:
+
+```bash title="Terminal"
+npx ario-deploy --version
+```
+
+## Project Setup
+
+ARIO Deploy works with any framework that generates a static build folder. The default deploy folder is `./dist`.
+
+
+
+
+
+ Initialize a new Next.js application:
+
+ ```bash title="Terminal"
+ npx create-next-app@latest my-arweave-app
+ cd my-arweave-app
+ ```
+
+ Enable static export by updating `next.config.js`:
+
+ ```javascript title="next.config.js"
+ /** @type {import('next').NextConfig} */
+ const nextConfig = {
+ output: 'export',
+ images: {
+ unoptimized: true,
+ },
+ trailingSlash: true,
+ }
+
+ module.exports = nextConfig
+ ```
+
+ - `output: 'export'` generates a static site in the `out` folder
+ - `images.unoptimized: true` prevents server-side image optimization
+ - `trailingSlash: true` ensures URLs work correctly on static hosting
+
+
+
+ ```bash title="Terminal"
+ npm install --save-dev @ar.io/deploy
+ ```
+
+ Update your `package.json` scripts:
+
+ ```json title="package.json"
+ {
+ "scripts": {
+ "dev": "next dev",
+ "build": "next build",
+ "deploy": "next build && ario-deploy deploy --deploy-folder out",
+ "deploy:arns": "next build && ario-deploy deploy --deploy-folder out --arns-name your-arns-name"
+ }
+ }
+ ```
+
+ Note the `--deploy-folder out` flag is required since Next.js exports to `./out` instead of the default `./dist`.
+
+
+
+
+
+
+
+ ```bash title="Terminal"
+ npm create vite@latest my-arweave-app -- --template react
+ cd my-arweave-app
+ npm install
+ ```
+
+
+
+ Update `vite.config.js` to use relative paths for Arweave:
+
+ ```javascript title="vite.config.js"
+ import { defineConfig } from 'vite'
+ import react from '@vitejs/plugin-react'
+
+ export default defineConfig({
+ plugins: [react()],
+ base: './', // Use relative paths for Arweave
+ })
+ ```
+
+ The `base: './'` setting ensures all asset paths are relative, which is required for proper loading on Arweave gateways.
+
+
+
+ ```bash title="Terminal"
+ npm install --save-dev @ar.io/deploy
+ ```
+
+ Update your `package.json` scripts:
+
+ ```json title="package.json"
+ {
+ "scripts": {
+ "dev": "vite",
+ "build": "vite build",
+ "deploy": "vite build && ario-deploy deploy",
+ "deploy:arns": "vite build && ario-deploy deploy --arns-name your-arns-name"
+ }
+ }
+ ```
+
+ Vite builds to `./dist` by default, which matches the ARIO Deploy default.
+
+
+
+
+
+
+
+ ```bash title="Terminal"
+ npm install --save-dev @ar.io/deploy
+ ```
+
+
+
+ Add a deploy command that points to your build output folder:
+
+ ```json title="package.json"
+ {
+ "scripts": {
+ "deploy": "ario-deploy deploy --deploy-folder ./public",
+ "deploy:arns": "ario-deploy deploy --deploy-folder ./public --arns-name your-arns-name"
+ }
+ }
+ ```
+
+ Replace `./public` with whatever directory contains your built static files (e.g., `./build`, `./out`, `./dist`).
+
+
+
+
+
+## Deploying from the Command Line
+
+### Upload Only (Quick Start)
+
+The simplest deployment uploads your build folder to Arweave and returns a transaction ID. No ArNS name is needed.
+
+
+
+ ```bash title="Terminal"
+ DEPLOY_KEY=$(base64 -i wallet.json) npx ario-deploy deploy --deploy-folder ./dist
+ ```
+
+ The `$(base64 -i wallet.json)` command encodes your JWK wallet on-the-fly without saving the encoded value to disk.
+
+
+
+ ```bash title="Terminal"
+ DEPLOY_KEY="0x1234567890abcdef..." npx ario-deploy deploy --deploy-folder ./dist --sig-type ethereum
+ ```
+
+ Replace `0x1234...` with your actual hex private key. Use `--sig-type polygon` or `--sig-type kyve` for those chains.
+
+
+
+ ```bash title="Terminal"
+ DEPLOY_KEY="your-base58-secret-key" npx ario-deploy deploy --deploy-folder ./dist --sig-type solana
+ ```
+
+ Or use a wallet file:
+
+ ```bash title="Terminal"
+ npx ario-deploy deploy --deploy-folder ./dist --wallet ~/.config/solana/id.json --sig-type solana
+ ```
+
+
+
+### With ArNS Update (Two-Key Model)
+
+To upload and update an ArNS name in one command, you need both keys:
+
+
+
+ When your upload key and ArNS authority key are different wallets:
+
+ ```bash title="Terminal"
+ DEPLOY_KEY=$(base64 -i wallet.json) \
+ ARNS_KEY="your-solana-base58-secret-key" \
+ npx ario-deploy deploy \
+ --deploy-folder ./dist \
+ --arns-name myapp
+ ```
+
+ Or using file paths:
+
+ ```bash title="Terminal"
+ npx ario-deploy deploy \
+ --deploy-folder ./dist \
+ --wallet ./wallet.json \
+ --arns-wallet ~/.config/solana/id.json \
+ --arns-name myapp
+ ```
+
+
+
+ When you use a single Solana wallet for both upload and ArNS:
+
+ ```bash title="Terminal"
+ DEPLOY_KEY="your-solana-base58-secret-key" \
+ ARNS_KEY="your-solana-base58-secret-key" \
+ npx ario-deploy deploy \
+ --deploy-folder ./dist \
+ --sig-type solana \
+ --arns-name myapp
+ ```
+
+
+
+
+ Regardless of what signer type you use for uploads, the ArNS key (`ARNS_KEY` or `--arns-wallet`) must always be a Solana key that controls the ANT (Arweave Name Token) for your ArNS name.
+
+
+### Interactive Mode
+
+If you are unsure about options or prefer a guided experience, run the deploy command with no flags:
+
+```bash title="Terminal"
+npx ario-deploy deploy
+```
+
+The interactive wizard prompts you for:
+- Deploy target (folder or file)
+- Signer type and wallet
+- Whether to update an ArNS name
+- ArNS name and undername
+- Solana cluster (mainnet or devnet)
+
+This is the easiest way to get started when you are exploring the tool for the first time.
+
+## On-Demand Payment
+
+Instead of pre-funding Turbo Credits, you can pay for deployments on-demand. ARIO Deploy will automatically convert tokens to credits at upload time with a 10% buffer to cover price fluctuations.
+
+
+
+ ```bash title="Terminal"
+ DEPLOY_KEY=$(base64 -i wallet.json) npx ario-deploy deploy \
+ --deploy-folder ./dist \
+ --on-demand ario \
+ --max-token-amount 2.0
+ ```
+
+ - `--on-demand ario` enables automatic ARIO-to-credits conversion
+ - `--max-token-amount 2.0` caps the maximum ARIO to spend (prevents unexpected costs)
+ - Your wallet must hold ARIO tokens
+
+
+
+ ```bash title="Terminal"
+ DEPLOY_KEY="0x1234..." npx ario-deploy deploy \
+ --deploy-folder ./dist \
+ --sig-type ethereum \
+ --on-demand base-eth \
+ --max-token-amount 0.01
+ ```
+
+ - `--on-demand base-eth` enables automatic ETH-to-credits conversion on Base Network
+ - Your wallet must have ETH on the **Base Network** (not Ethereum mainnet)
+
+
+ Base-ETH on-demand payment only works with Ethereum signer types. Ensure your wallet is funded with ETH on Base Network.
+
+
+
+
+
+ A typical static site (5-10 MB) costs approximately 0.1-0.5 ARIO. You can pre-fund credits at [console.ar.io/topup](https://console.ar.io/topup) to avoid on-demand conversion fees.
+
+
+## Deduplication (Smart Caching)
+
+ARIO Deploy automatically deduplicates files across deployments. When you redeploy an app where most files have not changed, only the new or modified files are uploaded. This saves time and money on repeat deployments.
+
+How it works:
+
+1. Each file is SHA-256 hashed before upload
+2. Hashes are compared against the local cache at `.ario-deploy/transaction-cache.json`
+3. Unchanged files reuse their existing Arweave transaction IDs
+4. Only new or modified files are uploaded and billed
+
+The cache uses LRU eviction with a default maximum of 10,000 entries.
+
+```bash title="Terminal"
+# Disable deduplication for a clean deploy
+npx ario-deploy deploy --no-dedupe
+
+# Customize cache size
+npx ario-deploy deploy --dedupe-cache-max-entries 5000
+```
+
+
+ You can commit `.ario-deploy/transaction-cache.json` to version control so team members benefit from shared deduplication. Alternatively, add it to `.gitignore` for per-machine caching. The GitHub Action handles caching automatically.
+
+
+## GitHub Action (Recommended CI/CD)
+
+The `ar-io/ar-io-deploy@v1` GitHub Action is the recommended way to automate deployments. It handles Node.js setup, deduplication caching, and PR comment notifications out of the box.
+
+### Production Deployment
+
+
+
+ In your GitHub repository, navigate to **Settings** > **Secrets and variables** > **Actions** and add:
+
+ | Secret | Format | Purpose |
+ |--------|--------|---------|
+ | `DEPLOY_KEY` | Base64 JWK, hex key, or base58 key | Pays for the Arweave upload |
+ | `ARNS_KEY` | Base58 Solana secret key | Updates the ArNS record |
+
+
+ For Arweave wallets, base64-encode the entire JWK file before adding it as a secret: `base64 -i wallet.json`. For Solana, use the base58 secret key from `solana-keygen export-private-key`.
+
+
+
+
+ ```yaml title=".github/workflows/deploy.yml"
+ name: Deploy to Permaweb
+
+ 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: '20'
+ cache: 'npm'
+
+ - name: Install and build
+ run: |
+ npm ci
+ npm run build
+
+ - name: Deploy to AR.IO
+ uses: ar-io/ar-io-deploy@v1
+ with:
+ deploy-key: ${{ secrets.DEPLOY_KEY }}
+ arns-key: ${{ secrets.ARNS_KEY }}
+ arns-name: your-arns-name
+ deploy-folder: ./dist
+ ```
+
+ Replace `your-arns-name` with your actual ArNS name and adjust `deploy-folder` if your framework outputs elsewhere (e.g., `./out` for Next.js).
+
+
+
+ Push to your main branch and check the **Actions** tab to monitor the deployment. On success, the action outputs:
+
+ - `tx-id` — the Arweave transaction ID
+ - `deployment-url` — the full ArNS URL (e.g., `https://myapp.ar.io`)
+ - `undername-used` — which undername was updated
+
+
+
+### PR Previews
+
+Enable PR previews to automatically deploy each pull request to a unique undername and post a comment with the preview URL:
+
+```yaml title=".github/workflows/preview.yml"
+name: PR Preview
+
+on:
+ pull_request:
+ types: [opened, synchronize, reopened, closed]
+
+jobs:
+ preview:
+ 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
+ if: github.event.action != 'closed'
+ 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: your-arns-name
+ deploy-folder: ./dist
+ preview: 'true'
+ github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+When `preview: 'true'` is set, the action:
+
+1. Auto-generates an undername from the PR number (e.g., `myrepo-pr-42`)
+2. Deploys the build to that undername (e.g., `https://myrepo-pr-42_myapp.ar.io`)
+3. Posts a comment on the PR with the preview URL
+4. Updates the comment on subsequent pushes
+5. Cleans up the undername when the PR is closed
+
+
+ The GitHub Action automatically saves and restores the deduplication cache between runs using `actions/cache`. You do not need to configure anything extra.
+
+
+### Action Inputs Reference
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `deploy-key` | Yes | — | Upload key (Arweave JWK base64, hex, or base58) |
+| `arns-key` | Yes | — | ArNS authority key (Solana base58) |
+| `arns-name` | Yes | — | ArNS name to update |
+| `deploy-folder` | No | `./dist` | Path to built static files |
+| `deploy-file` | No | — | Single file to deploy (alternative) |
+| `sig-type` | No | `arweave` | Upload signer type |
+| `undername` | No | `@` | Undername to update |
+| `ttl-seconds` | No | `3600` | TTL for the ArNS record |
+| `preview` | No | `false` | Enable PR preview mode |
+| `github-token` | No | — | Required when `preview` is enabled |
+| `on-demand` | No | — | On-demand payment token (`ario` or `base-eth`) |
+| `max-token-amount` | No | — | Max spend for on-demand payment |
+| `no-dedupe` | No | `false` | Disable deduplication cache |
+
+## CLI in GitHub Actions (Alternative)
+
+If you need more control than the composite action provides, you can use the CLI directly in your workflow:
+
+```yaml title=".github/workflows/deploy-cli.yml"
+name: Deploy via CLI
+
+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: '20'
+ cache: 'npm'
+
+ - name: Install dependencies and build
+ run: |
+ npm ci
+ npm run build
+
+ - name: Install ARIO Deploy
+ run: npm install -g @ar.io/deploy
+
+ - name: Deploy
+ env:
+ DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
+ ARNS_KEY: ${{ secrets.ARNS_KEY }}
+ run: |
+ ario-deploy deploy \
+ --deploy-folder ./dist \
+ --arns-name your-arns-name \
+ --sig-type arweave
+```
+
+
+ Use the CLI directly when you need custom pre/post-deploy steps, conditional logic around the deploy command, or integration with other tools in the same job step.
+
+
+## Claude Code / AI Agent Deployment
+
+ARIO Deploy includes a built-in Claude Code skill that enables natural-language deployments. If you use [Claude Code](https://claude.ai/code) in your project, you can deploy by saying:
+
+> "Deploy to ar.io"
+
+The skill will:
+
+1. Detect your build folder automatically
+2. Check for wallet configuration
+3. Run the appropriate deploy command
+4. Report the transaction ID and live URL
+
+To add the skill to your project, copy the skill file from the [@ar.io/deploy repository](https://github.com/ar-io/ar-io-deploy/tree/main/examples/claude-skill) into your project's `.claude/skills/` directory.
+
+
+ On first use, the skill guides you through wallet creation, ArNS name registration, and funding. It supports both upload-only and full ArNS deployments.
+
+
+## Summary
+
+You now know how to deploy permanent web applications using `@ar.io/deploy`:
+
+- **Static site setup** for Next.js, React + Vite, or any framework with static output
+- **Two-key model** separating upload payment (`DEPLOY_KEY`) from ArNS authority (`ARNS_KEY`)
+- **Five signer types** — Arweave, Ethereum, Polygon, KYVE, and Solana
+- **On-demand payment** with ARIO tokens or Base-ETH for pay-as-you-go deployments
+- **Smart deduplication** that skips unchanged files across deployments
+- **GitHub Action** (`ar-io/ar-io-deploy@v1`) for automated production deploys and PR previews
+- **Interactive mode** for guided first-time deployments
+- **AI-assisted deployment** via Claude Code natural language commands
+
+
+ }
+ />
+ }
+ />
+
diff --git a/content/build/guides/hosting-decentralised-apps/deploying-with-arlink.mdx b/content/build/guides/hosting-decentralised-apps/deploying-with-arlink.mdx
index 088bae729..f6159cb67 100644
--- a/content/build/guides/hosting-decentralised-apps/deploying-with-arlink.mdx
+++ b/content/build/guides/hosting-decentralised-apps/deploying-with-arlink.mdx
@@ -11,7 +11,7 @@ import { Zap, Github, Globe, Sparkles, FileCode, Rocket, GitBranch } from 'lucid
## Introduction
-In the previous guides in this series, we've used a CLI tool called `permaweb-deploy` to configure and host decentralised apps on ar.io.
+In the previous guides in this series, we've used a CLI tool called `@ar.io/deploy` to configure and host decentralised apps on ar.io.
In this guide we'll be using [Arlink](https://arlink.ar.io), a visual, web-based platform for hosting decentralised apps on ar.io without needing command-line tools.
@@ -44,9 +44,9 @@ Arlink is a web-based deployment platform that simplifies hosting applications o
-All applications that can be deployed with `permaweb-deploy` CLI can also be deployed with Arlink. Choose the tool that fits your workflow:
+All applications that can be deployed with `ario-deploy` CLI can also be deployed with Arlink. Choose the tool that fits your workflow:
- **Arlink**: Visual workflows, quick deployments, smaller projects (under 10MB)
-- **permaweb-deploy**: CI/CD pipelines, large applications, custom automation
+- **ario-deploy**: CI/CD pipelines, large applications, custom automation
See [Limitations & Considerations](#limitations--considerations) below to help decide.
@@ -137,7 +137,7 @@ Click **Deploy** to start the build process. Arlink will clone your repository,
- Large apps (5-10MB): 5-10 minutes
-Arlink enforces a **10MB max build output** and **10-minute build timeout**. For larger applications, use `permaweb-deploy` CLI instead.
+Arlink enforces a **10MB max build output** and **10-minute build timeout**. For larger applications, use `ario-deploy` CLI instead.
@@ -201,10 +201,10 @@ npm run build
du -sh dist/ # or build/, out/, etc.
```
-If your build exceeds 10MB, use `permaweb-deploy` CLI instead.
+If your build exceeds 10MB, use `ario-deploy` CLI instead.
-### Comparison: Arlink vs permaweb-deploy CLI
+### Comparison: Arlink vs ario-deploy CLI
Choose the right tool for your use case:
@@ -241,7 +241,7 @@ Choose the right tool for your use case:
- Limited undername configuration options
-If you outgrow Arlink's capabilities, all your existing deployments can be managed with `permaweb-deploy` CLI. See the [other guides in this series](/build/guides/hosting-decentralised-apps) for CLI deployment instructions.
+If you outgrow Arlink's capabilities, all your existing deployments can be managed with `ario-deploy` CLI. See the [other guides in this series](/build/guides/hosting-decentralised-apps) for CLI deployment instructions.
## Continuous Deployment
@@ -284,6 +284,6 @@ You now know how to deploy applications using Arlink's visual interface:
- **Build monitoring** with real-time logs and progress tracking
- **Understanding limitations** to choose between Arlink and CLI tools for your project needs
-Arlink provides a quick and accessible way to deploy smaller applications. For larger builds, advanced CI/CD, or custom deployments, consider using the `permaweb-deploy` CLI covered in earlier guides.
+Arlink provides a quick and accessible way to deploy smaller applications. For larger builds, advanced CI/CD, or custom deployments, consider using the `ario-deploy` CLI covered in earlier guides.
In our final guide we'll explore deploying using the ArDrive web UI.
\ No newline at end of file
diff --git a/content/build/guides/hosting-decentralised-apps/deploying-with-permaweb-deploy.mdx b/content/build/guides/hosting-decentralised-apps/deploying-with-permaweb-deploy.mdx
deleted file mode 100644
index f0b5e4600..000000000
--- a/content/build/guides/hosting-decentralised-apps/deploying-with-permaweb-deploy.mdx
+++ /dev/null
@@ -1,505 +0,0 @@
----
-title: "Deploying with Permaweb-Deploy"
-description: "Learn how to deploy permanent web applications to Arweave using the permaweb-deploy CLI tool with Next.js and React"
----
-
-import { Callout } from 'fumadocs-ui/components/callout';
-import { Steps, Step } from 'fumadocs-ui/components/steps';
-import { Card, Cards } from 'fumadocs-ui/components/card';
-import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-import {
- Terminal,
- Rocket,
- Wallet,
- Zap,
- GitBranch,
- BookOpen,
-} from 'lucide-react';
-
-Permaweb-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, 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.
-
-
- Check out the [series introduction](/build/guides/hosting-decentralised-apps) to learn about permanent hosting and ArNS domains.
-
-
-## Prerequisites
-
-Before starting, ensure you have:
-
-- **Node.js 18+** - Download from [nodejs.org](https://nodejs.org/)
-- **Arweave or EVM Wallet** - You'll need the private key or JWK file
-- **ArNS Name** - Register one at [arns.ar.io](https://arns.ar.io)
-- **Command Line Familiarity** - Basic terminal/shell knowledge
-
-
- Always use a dedicated wallet for deployments to minimize security risks. Never commit your private keys to version control.
-
-
-## 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.
-
-
-
-
-
- Initialize a new Next.js application:
-
- ```bash title="Terminal"
- npx create-next-app@latest my-permaweb-app
- cd my-permaweb-app
- ```
-
- When prompted, select your preferences. For permanent hosting, **enable static export** by updating `next.config.js`:
-
- ```javascript title="next.config.js"
- /** @type {import('next').NextConfig} */
- const nextConfig = {
- output: 'export',
- images: {
- unoptimized: true,
- },
- trailingSlash: true,
- }
-
- module.exports = nextConfig
- ```
-
- - `output: 'export'` generates a static site in the `out` folder
- - `images.unoptimized: true` prevents server-side image optimization
- - `trailingSlash: true` ensures URLs work correctly on static hosting
-
-
-
- Add permaweb-deploy as a development dependency:
-
- ```bash title="Terminal"
- npm install --save-dev permaweb-deploy
- ```
-
-
-
- Update your `package.json` to include deployment commands:
-
- ```json title="package.json"
- {
- "scripts": {
- "dev": "next dev",
- "build": "next build",
- "deploy": "next build && permaweb-deploy deploy --arns-name your-arns-name --deploy-folder out"
- }
- }
- ```
-
- Replace `your-arns-name` with your actual ArNS domain name. Note the `--deploy-folder out` flag is required since Next.js exports to `./out` instead of the default `./dist`.
-
-
-
-
-
-
-
- Initialize a new Vite application with React:
-
- ```bash title="Terminal"
- npm create vite@latest my-permaweb-app -- --template react
- cd my-permaweb-app
- npm install
- ```
-
-
-
- Update `vite.config.js` to use relative paths for Arweave:
-
- ```javascript title="vite.config.js"
- import { defineConfig } from 'vite'
- import react from '@vitejs/plugin-react'
-
- export default defineConfig({
- plugins: [react()],
- base: './', // Use relative paths for Arweave
- })
- ```
-
- The `base: './'` setting ensures all asset paths are relative, which is required for proper loading on Arweave gateways.
-
-
-
- Add permaweb-deploy as a development dependency:
-
- ```bash title="Terminal"
- npm install --save-dev permaweb-deploy
- ```
-
-
-
- Update your `package.json` to include deployment commands:
-
- ```json title="package.json"
- {
- "scripts": {
- "dev": "vite",
- "build": "vite build",
- "deploy": "vite build && permaweb-deploy deploy --arns-name your-arns-name"
- }
- }
- ```
-
- Replace `your-arns-name` with your actual ArNS domain 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).
-
-
- Always use a dedicated wallet for deployments to minimize security risks. Never commit wallet files or keys to version control.
-
-
-
-
- Permaweb-deploy uses [Turbo](https://console.ar.io) to upload files to Arweave. Before deploying, ensure your wallet has sufficient credits.
-
- Visit the [Console app](https://console.ar.io/topup) and connect your deployment wallet to view your current balance.
-
-
- A typical static site (5-10 MB) costs approximately 0.1-0.5 ARIO. Credits are applied instantly and remain in your wallet for future deployments.
-
-
-
-
- The `npm run deploy` command we configured earlier will build your app and deploy it to Arweave. Use the `DEPLOY_KEY` environment variable to pass your wallet credentials inline:
-
-
-
- For Arweave wallets, base64 encode your JWK file and pass it inline:
-
- ```bash title="Terminal"
- DEPLOY_KEY=$(base64 -i wallet.json) npm run deploy
- ```
-
- This command will:
- 1. Build your application (`next build` or `vite build`)
- 2. Deploy to Arweave using your base64-encoded wallet
-
- The `$(base64 -i wallet.json)` command encodes your wallet on-the-fly without saving it to disk.
-
-
-
- For EVM wallets (Ethereum, Polygon, Base, KYVE), use your raw private key:
-
- ```bash title="Terminal"
- DEPLOY_KEY="0x1234567890abcdef..." npm run deploy
- ```
-
- This command will:
- 1. Build your application (`next build` or `vite build`)
- 2. Deploy to Arweave using your EVM wallet
-
- Replace `0x1234...` with your actual private key from MetaMask or your wallet provider.
-
-
- For EVM wallets, ensure your deploy script in `package.json` includes the `--sig-type` flag (e.g., `--sig-type ethereum`).
-
-
-
-
-
-
- Permaweb-deploy will:
-
- 1. **Upload files** to Arweave via Turbo
- 2. **Create a manifest** with SPA fallback detection
- 3. **Update ArNS records** to point to the new transaction
- 4. **Tag the deployment** with your current git commit hash
-
- Expected output:
-
- ```
- -------------------- 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 [@]
-
- ```
-
-
-
-
- ArNS updates typically propagate across the gateway network within 60 seconds (the default TTL). You may need to hard refresh your browser to see changes immediately.
-
-
-## 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.
-
-
-
- Update your `package.json` to include an on-demand deployment script:
-
-
-
-
-
- For Arweave wallets using ARIO tokens:
-
- ```json title="package.json"
- {
- "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"
- }
- }
- ```
-
- - `--on-demand ario` enables ARIO payment mode
- - `--max-token-amount 2.0` sets maximum ARIO to spend (prevents unexpected costs)
-
-
-
- For EVM wallets using Base-ETH:
-
- ```json title="package.json"
- {
- "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"
- }
- }
- ```
-
- - `--sig-type ethereum` required for EVM wallets
- - `--on-demand base-eth` enables Base Network payment
- - Wallet must be funded with ETH on Base Network
-
-
- Base-ETH on-demand payment only works with Ethereum signer types. Your wallet must have ETH on the Base Network, not Ethereum mainnet.
-
-
-
-
-
-
-
-
- For Arweave wallets using ARIO tokens:
-
- ```json title="package.json"
- {
- "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"
- }
- }
- ```
-
- - `--on-demand ario` enables ARIO payment mode
- - `--max-token-amount 2.0` sets maximum ARIO to spend (prevents unexpected costs)
-
-
-
- For EVM wallets using Base-ETH:
-
- ```json title="package.json"
- {
- "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"
- }
- }
- ```
-
- - `--sig-type ethereum` required for EVM wallets
- - `--on-demand base-eth` enables Base Network payment
- - Wallet must be funded with ETH on Base Network
-
-
- Base-ETH on-demand payment only works with Ethereum signer types. Your wallet must have ETH on the Base Network, not Ethereum mainnet. See [Base documentation](https://docs.base.org/) for getting testnet or mainnet ETH.
-
-
-
-
-
-
-
-
- Run the on-demand deployment command with your wallet credentials:
-
-
-
- ```bash title="Terminal"
- DEPLOY_KEY=$(base64 -i wallet.json) npm run deploy:on-demand
- ```
-
- The tool will automatically convert ARIO to Turbo Credits as needed for the deployment.
-
-
-
- ```bash title="Terminal"
- DEPLOY_KEY="0x1234567890abcdef..." npm run deploy:on-demand
- ```
-
- The tool will automatically convert Base-ETH to Turbo Credits as needed for the deployment.
-
-
-
-
-
-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.
-
-
-
- In your GitHub repository:
-
- 1. Navigate to **Settings** → **Secrets and variables** → **Actions**
- 2. Click **New repository secret**
- 3. Name: `DEPLOY_KEY`
- 4. Value: Paste in your wallet key
- 5. Click **Add secret**
-
-
- For Arweave wallets, encode the entire JWK file to base64 before adding it as a secret. For EVM wallets, use the raw private key with the `0x` prefix.
-
-
-
-
- Create `.github/workflows/deploy.yml`:
-
- ```yaml title=".github/workflows/deploy.yml"
- 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 }}
- ```
-
- This workflow:
- - Triggers on pushes to the `main` branch
- - Checks out your code
- - Installs dependencies
- - Runs your `deploy` script with the secret `DEPLOY_KEY`
-
-
-
- Adjust the workflow based on your needs:
-
-
-
- For Next.js, ensure your deploy script includes `--deploy-folder out`:
-
- ```json title="package.json"
- {
- "scripts": {
- "deploy": "next build && permaweb-deploy deploy --arns-name myapp --deploy-folder out"
- }
- }
- ```
-
-
-
- For Vite, the default `./dist` folder works automatically:
-
- ```json title="package.json"
- {
- "scripts": {
- "deploy": "vite build && permaweb-deploy deploy --arns-name myapp"
- }
- }
- ```
-
-
-
- For on-demand deployments, add the appropriate flags:
-
- ```json title="package.json"
- {
- "scripts": {
- "deploy": "vite build && permaweb-deploy deploy --arns-name myapp --on-demand ario --max-token-amount 2.0"
- }
- }
- ```
-
- The workflow will automatically convert tokens as needed during CI runs.
-
-
-
-
-
- Make a commit and push to your main branch:
-
- ```bash title="Terminal"
- git add .
- git commit -m "Set up automated deployments"
- git push origin main
- ```
-
- Check the **Actions** tab in your GitHub repository to monitor the deployment progress.
-
-
-
-
- Each push triggers a new deployment. For high-traffic repositories, consider adding conditions to deploy only when specific files change, or use manual workflow triggers.
-
-
-
-## 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.
-
diff --git a/content/build/guides/hosting-decentralised-apps/index.mdx b/content/build/guides/hosting-decentralised-apps/index.mdx
index 15cde5bca..248ccdcc4 100644
--- a/content/build/guides/hosting-decentralised-apps/index.mdx
+++ b/content/build/guides/hosting-decentralised-apps/index.mdx
@@ -44,9 +44,9 @@ We'll cover the following:
icon={}
/>
}
/>
}
/>
diff --git a/content/build/guides/hosting-decentralised-apps/meta.json b/content/build/guides/hosting-decentralised-apps/meta.json
index 3ca26b6f7..abd64bfd3 100644
--- a/content/build/guides/hosting-decentralised-apps/meta.json
+++ b/content/build/guides/hosting-decentralised-apps/meta.json
@@ -4,7 +4,7 @@
"pages": [
"migrating-your-app-to-new-sdks",
"deploy-permanent-dapp",
- "deploying-with-permaweb-deploy",
+ "deploying-with-ario-deploy",
"using-undernames-for-versioning",
"deploying-with-arlink",
"hosting-with-ardrive"
diff --git a/content/build/guides/hosting-decentralised-apps/using-undernames-for-versioning.mdx b/content/build/guides/hosting-decentralised-apps/using-undernames-for-versioning.mdx
index 36e91dd10..605278da3 100644
--- a/content/build/guides/hosting-decentralised-apps/using-undernames-for-versioning.mdx
+++ b/content/build/guides/hosting-decentralised-apps/using-undernames-for-versioning.mdx
@@ -9,7 +9,7 @@ import { Card, Cards } from 'fumadocs-ui/components/card';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { GitBranch, Code, Rocket, Network, Settings, RefreshCw, CheckCircle, Zap, Upload } from 'lucide-react';
-In the [previous guide](/build/guides/hosting-decentralised-apps/deploying-with-permaweb-deploy), you deployed your application to your base ArNS name. Now you'll learn how to manage multiple versions and environments using **undernames** - subdomains under your ArNS name.
+In the [previous guide](/build/guides/hosting-decentralised-apps/deploying-with-ario-deploy), you deployed your application to your base ArNS name. Now you'll learn how to manage multiple versions and environments using **undernames** - subdomains under your ArNS name.
## What You'll Learn
@@ -67,10 +67,10 @@ In your `my-permaweb-app` project from the previous guide, update `package.json`
"scripts": {
"dev": "next dev",
"build": "next build",
- "deploy": "next build && permaweb-deploy deploy --arns-name your-arns-name --deploy-folder out",
- "deploy:dev": "next build && permaweb-deploy deploy --arns-name your-arns-name --deploy-folder out --undername dev --ttl-seconds 60",
- "deploy:staging": "next build && permaweb-deploy deploy --arns-name your-arns-name --deploy-folder out --undername staging --ttl-seconds 60",
- "deploy:prod": "next build && permaweb-deploy deploy --arns-name your-arns-name --deploy-folder out --ttl-seconds 3600"
+ "deploy": "next build && ario-deploy deploy --arns-name your-arns-name --deploy-folder out",
+ "deploy:dev": "next build && ario-deploy deploy --arns-name your-arns-name --deploy-folder out --undername dev --ttl-seconds 60",
+ "deploy:staging": "next build && ario-deploy deploy --arns-name your-arns-name --deploy-folder out --undername staging --ttl-seconds 60",
+ "deploy:prod": "next build && ario-deploy deploy --arns-name your-arns-name --deploy-folder out --ttl-seconds 3600"
}
}
```
@@ -84,10 +84,10 @@ In your `my-permaweb-app` project from the previous guide, update `package.json`
"scripts": {
"dev": "vite",
"build": "vite build",
- "deploy": "vite build && permaweb-deploy deploy --arns-name your-arns-name",
- "deploy:dev": "vite build && permaweb-deploy deploy --arns-name your-arns-name --undername dev --ttl-seconds 60",
- "deploy:staging": "vite build && permaweb-deploy deploy --arns-name your-arns-name --undername staging --ttl-seconds 60",
- "deploy:prod": "vite build && permaweb-deploy deploy --arns-name your-arns-name --ttl-seconds 60"
+ "deploy": "vite build && ario-deploy deploy --arns-name your-arns-name",
+ "deploy:dev": "vite build && ario-deploy deploy --arns-name your-arns-name --undername dev --ttl-seconds 60",
+ "deploy:staging": "vite build && ario-deploy deploy --arns-name your-arns-name --undername staging --ttl-seconds 60",
+ "deploy:prod": "vite build && ario-deploy deploy --arns-name your-arns-name --ttl-seconds 60"
}
}
```
@@ -130,7 +130,7 @@ Create a script that automatically archives based on your `package.json` version
// Deploy to version-specific undername (build already done by npm script)
execSync(
- `permaweb-deploy deploy --arns-name your-arns-name --deploy-folder out --undername v${version} --ttl-seconds 3600`,
+ `ario-deploy deploy --arns-name your-arns-name --deploy-folder out --undername v${version} --ttl-seconds 3600`,
{ stdio: 'inherit' }
);
@@ -142,9 +142,9 @@ Create a script that automatically archives based on your `package.json` version
```json title="package.json"
{
"scripts": {
- "deploy:dev": "next build && permaweb-deploy deploy --arns-name your-arns-name --deploy-folder out --undername dev --ttl-seconds 60",
- "deploy:staging": "next build && permaweb-deploy deploy --arns-name your-arns-name --deploy-folder out --undername staging --ttl-seconds 60",
- "deploy:prod": "next build && permaweb-deploy deploy --arns-name your-arns-name --deploy-folder out --ttl-seconds 3600",
+ "deploy:dev": "next build && ario-deploy deploy --arns-name your-arns-name --deploy-folder out --undername dev --ttl-seconds 60",
+ "deploy:staging": "next build && ario-deploy deploy --arns-name your-arns-name --deploy-folder out --undername staging --ttl-seconds 60",
+ "deploy:prod": "next build && ario-deploy deploy --arns-name your-arns-name --deploy-folder out --ttl-seconds 3600",
"deploy:archive": "next build && node scripts/deploy-archive.js"
}
}
@@ -163,7 +163,7 @@ Create a script that automatically archives based on your `package.json` version
// Deploy to version-specific undername (build already done by npm script)
execSync(
- `permaweb-deploy deploy --arns-name your-arns-name --undername v${version} --ttl-seconds 3600`,
+ `ario-deploy deploy --arns-name your-arns-name --undername v${version} --ttl-seconds 3600`,
{ stdio: 'inherit' }
);
@@ -175,9 +175,9 @@ Create a script that automatically archives based on your `package.json` version
```json title="package.json"
{
"scripts": {
- "deploy:dev": "vite build && permaweb-deploy deploy --arns-name your-arns-name --undername dev --ttl-seconds 60",
- "deploy:staging": "vite build && permaweb-deploy deploy --arns-name your-arns-name --undername staging --ttl-seconds 60",
- "deploy:prod": "vite build && permaweb-deploy deploy --arns-name your-arns-name --ttl-seconds 3600",
+ "deploy:dev": "vite build && ario-deploy deploy --arns-name your-arns-name --undername dev --ttl-seconds 60",
+ "deploy:staging": "vite build && ario-deploy deploy --arns-name your-arns-name --undername staging --ttl-seconds 60",
+ "deploy:prod": "vite build && ario-deploy deploy --arns-name your-arns-name --ttl-seconds 3600",
"deploy:archive": "vite build && node scripts/deploy-archive.js"
}
}
@@ -209,9 +209,9 @@ admin → Admin panel
```json title="package.json"
{
"scripts": {
- "deploy:marketing": "permaweb-deploy deploy --arns-name your-arns-name --deploy-folder ./marketing/dist --ttl-seconds 3600",
- "deploy:app": "permaweb-deploy deploy --arns-name your-arns-name --undername app --deploy-folder ./app/dist --ttl-seconds 60",
- "deploy:docs": "permaweb-deploy deploy --arns-name your-arns-name --undername docs --deploy-folder ./docs/dist --ttl-seconds 1800",
+ "deploy:marketing": "ario-deploy deploy --arns-name your-arns-name --deploy-folder ./marketing/dist --ttl-seconds 3600",
+ "deploy:app": "ario-deploy deploy --arns-name your-arns-name --undername app --deploy-folder ./app/dist --ttl-seconds 60",
+ "deploy:docs": "ario-deploy deploy --arns-name your-arns-name --undername docs --deploy-folder ./docs/dist --ttl-seconds 1800",
"deploy:all": "npm run deploy:marketing && npm run deploy:app && npm run deploy:docs"
}
}
@@ -223,7 +223,7 @@ Each component can be deployed independently or all at once with `npm run deploy
## Automating Environment Deployments
-Building on the [GitHub Actions workflow](/build/guides/hosting-decentralised-apps/deploying-with-permaweb-deploy#automating-with-github-actions) from the previous guide, let's create environment-specific workflows that deploy based on branch activity.
+Building on the [GitHub Actions workflow](/build/guides/hosting-decentralised-apps/deploying-with-ario-deploy#automating-with-github-actions) from the previous guide, let's create environment-specific workflows that deploy based on branch activity.
@@ -401,5 +401,5 @@ You now know how to manage multiple environments using ArNS undernames:
- **GitHub Actions automation** for branch-based deployments
- **Instant rollbacks** through the ArNS app interface
-In our next guides we're explore other tools you can use to host websites on ar.io without needing to configure `permaweb-deploy`.
+In our next guides we're explore other tools you can use to host websites on ar.io without needing to configure `ario-deploy`.
diff --git a/redirects.mjs b/redirects.mjs
index 7224ed929..e59f2d1e0 100644
--- a/redirects.mjs
+++ b/redirects.mjs
@@ -1,5 +1,12 @@
// Comprehensive redirects from old URL structure (main branch) to new structure (fumadocs branch)
const redirects = [
+ // Renamed pages
+ {
+ source: '/build/guides/hosting-decentralised-apps/deploying-with-permaweb-deploy',
+ destination: '/build/guides/hosting-decentralised-apps/deploying-with-ario-deploy',
+ permanent: true,
+ },
+
// Main documentation sections
{
source: '/introduction',