Installation

System Requirements

Node.js

Version 18 or higher requiredCheck your version:

node --version

Package Manager

Choose one:

npm (bundled with Node.js)
yarn
pnpm

Sui Wallet

Browser extension for wallet connectionInstall Sui Wallet

Testnet SUI

Required for transactionsGet testnet tokens

Installation Methods

npm
yarn
pnpm

Using npm

# Clone the repository
git clone <repository-url>
cd tuna

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env.local

# Start development server
npm run dev

Using Yarn

# Clone the repository
git clone <repository-url>
cd tuna

# Install dependencies
yarn install

# Copy environment configuration
cp .env.example .env.local

# Start development server
yarn dev

Using pnpm

# Clone the repository
git clone <repository-url>
cd tuna

# Install dependencies
pnpm install

# Copy environment configuration
cp .env.example .env.local

# Start development server
pnpm dev

Dependencies

TUNA uses the following key dependencies:

Core Dependencies

{
  "@mysten/dapp-kit": "^0.19.11",
  "@mysten/sui.js": "^0.54.1",
  "@tanstack/react-query": "^5.90.12",
  "react": "^19.2.0",
  "react-dom": "^19.2.0",
  "react-router-dom": "^7.10.1",
  "gsap": "^3.13.0"
}

@mysten/dapp-kit

Official Sui dApp integration kit providing:

Wallet connection and management
Transaction signing
Account state management
React hooks for Sui interactions

@mysten/sui.js

Sui TypeScript SDK for:

Building transactions
Querying blockchain state
Interacting with smart contracts
RPC client functionality

@tanstack/react-query

Data fetching and state management:

Automatic caching and revalidation
Loading and error states
Optimistic updates
Background data synchronization

React 19

Modern React features:

Improved server components
Enhanced concurrent rendering
Better TypeScript support
Performance optimizations

Environment Configuration

Create Environment File

Copy the example environment file:

cp .env.example .env.local

Use .env.local for local development. This file is automatically ignored by git.

Configure Network Settings

Set your Sui network configuration:

# Network Configuration
VITE_SUI_NETWORK=testnet
VITE_SUI_RPC_URL=https://fullnode.testnet.sui.io:443

For development, always use testnet. Mainnet deployment requires additional configuration and real SUI tokens.

Set Contract Addresses

Configure the deployed smart contract addresses:

# Contract Addresses (Testnet)
VITE_PACKAGE_ID=0xc19c25a9e42f77c2466a1df42d99a160a65a8800711eef447bb8da441df33c9e
VITE_REGISTRY_ID=0x65fa3ee1fa53af68c36dd47b525392dfb844726af980f758c1b6dc353a30e962
VITE_ADMIN_CAP_ID=0x87c090e5a60dd505d3ef7634e6f32ced2134640f56b329946ab920a3a9299f6e

These addresses are specific to the TUNA testnet deployment. Don’t change them unless you’re deploying your own contracts.

Configure Walrus Storage

Set up Walrus decentralized storage endpoints:

# Walrus Configuration (Testnet)
VITE_WALRUS_PUBLISHER_URL=https://publisher.walrus-testnet.walrus.space/v1/store
VITE_WALRUS_AGGREGATOR_URL=https://aggregator.walrus-testnet.walrus.space/v1

Walrus is used for storing article content and media in a decentralized manner. The aggregator fetches content, while the publisher handles uploads.

Configuration Reference

All configuration is loaded from environment variables and consolidated in src/config/index.ts:

// src/config/index.ts
export const CONTRACT_CONFIG = {
  PACKAGE_ID: import.meta.env.VITE_PACKAGE_ID,
  REGISTRY_ID: import.meta.env.VITE_REGISTRY_ID,
  ADMIN_CAP_ID: import.meta.env.VITE_ADMIN_CAP_ID,
  MODULE_NAME: 'news_registry',
} as const;

Development Server

Available Scripts

TUNA includes several npm scripts from package.json:

{
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "lint": "eslint .",
    "preview": "vite preview"
  }
}

npm run dev

Start the development server with hot module replacementRuns on: http://localhost:5173

npm run build

Build for productionOutputs to: dist/

npm run lint

Run ESLint for code qualityChecks all .ts and .tsx files

npm run preview

Preview production build locallyServes the dist/ folder

Development Workflow

Start Development Server

npm run dev

The server starts on http://localhost:5173 with:

⚡️ Fast HMR (Hot Module Replacement)
🔄 Automatic page reload on changes
📊 React Query DevTools
🐛 Source maps for debugging

Make Changes

Edit any file in src/ and see changes instantly:

tuna/
├── src/
│   ├── components/     # UI components
│   ├── hooks/          # Custom React hooks
│   ├── lib/            # Utilities and helpers
│   ├── types/          # TypeScript type definitions
│   ├── config/         # Configuration
│   ├── App.tsx         # Main app component
│   └── main.tsx        # Application entry point

Run Linting

Check code quality before committing:

npm run lint

ESLint will check for:

TypeScript errors
React best practices
Code style issues

Build for Production

Create an optimized production build:

npm run build

This will:

Type-check with TypeScript
Bundle and minify code
Optimize assets
Generate source maps

Project Structure

Understanding the TUNA codebase:

tuna/
├── src/
│   ├── components/           # React components
│   │   ├── NewsCard.tsx      # Article card display
│   │   ├── TipModal.tsx      # Tipping interface
│   │   ├── CommentSection.tsx # Comments UI
│   │   └── ...
│   ├── hooks/                # Custom React hooks
│   │   ├── useNews.ts        # Fetch news articles
│   │   ├── useComments.ts    # Fetch comments
│   │   └── ...
│   ├── lib/                  # Utility functions
│   │   ├── sui.ts            # Sui transaction builders
│   │   ├── walrus.ts         # Walrus integration
│   │   └── utils.ts          # Helper functions
│   ├── types/                # TypeScript types
│   │   └── index.ts          # Type definitions
│   ├── config/               # Configuration
│   │   └── index.ts          # App configuration
│   ├── App.tsx               # Main application
│   ├── main.tsx              # Entry point
│   └── index.css             # Global styles
├── public/                   # Static assets
├── .env.example              # Environment template
├── .env.local                # Local configuration (gitignored)
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
├── vite.config.ts            # Vite configuration
└── README.md                 # Project documentation

Wallet Setup

Install Sui Wallet

Download and install the Sui Wallet browser extension:

Other compatible wallets include Suiet, Ethos Wallet, and Martian Wallet.

Create or Import Wallet

Follow the wallet setup wizard:

Create a new wallet or import existing
Save your recovery phrase securely
Set a strong password
Complete the setup

Never share your recovery phrase or private keys with anyone. TUNA developers will never ask for this information.

Switch to Testnet

Configure your wallet for testnet:

Open Sui Wallet
Click settings (⚙️ icon)
Navigate to Network
Select Testnet

TUNA currently runs on Sui testnet. Make sure your wallet is on the correct network.

Get Testnet Tokens

Obtain testnet SUI from the faucet:

Join the Sui Discord
Go to the #testnet-faucet channel
Use the command: !faucet <your-address>
Wait for tokens to arrive

Alternatively, use the web faucet

Verification

Verify your installation:

Check Installation
Test Development Server
Verify Configuration
Test Wallet Connection

# Verify Node.js version
node --version  # Should be 18 or higher

# Verify npm is working
npm --version

# Check dependencies are installed
npm list --depth=0

# Start the server
npm run dev

# You should see:
# VITE v7.2.5  ready in XXX ms
# ➜  Local:   http://localhost:5173/
# ➜  Network: use --host to expose

Open http://localhost:5173 in your browser.

Check that environment variables are loaded:

// Add this temporarily to src/App.tsx
console.log('Contract Config:', CONTRACT_CONFIG);
console.log('Network:', NETWORK_CONFIG.NETWORK);

Open browser console and verify the output.

Open the app at http://localhost:5173
Click “Connect Wallet”
Approve the connection
Verify your address appears in the UI

If successful, you’re ready to use TUNA!

Troubleshooting

Installation Errors

Problem: npm install fails with errorsSolutions:

Clear npm cache: npm cache clean --force
Delete node_modules and package-lock.json, then reinstall
Use Node.js LTS version (18 or 20)
Try using yarn or pnpm instead
Check for network/firewall issues

Port Already in Use

Problem: Port 5173 is already in useSolutions:

Kill the process using port 5173
Use a different port: npm run dev -- --port 3000
Check for other Vite dev servers running

TypeScript Errors

Problem: TypeScript compilation errorsSolutions:

Ensure all dependencies are installed
Run npm install @types/node -D
Check tsconfig.json is present
Restart your IDE/editor
Run tsc --noEmit to see all errors

Environment Variables Not Loading

Problem: Configuration values are undefinedSolutions:

Ensure file is named .env.local (not .env)
Restart the dev server after changing .env.local
Verify all variables start with VITE_
Check for syntax errors in the env file
Use import.meta.env.VITE_* to access variables

Wallet Connection Issues

Problem: Cannot connect walletSolutions:

Install Sui Wallet extension
Unlock your wallet
Switch to testnet in wallet settings
Refresh the page
Clear browser cache
Try a different browser

Next Steps

Quickstart Guide

Get up and running in 5 minutes

Core Concepts

Learn how TUNA works

Integration Guide

Start building with TUNA

Features

Explore TUNA’s key features

Successfully installed TUNA? Head over to the Quickstart to connect your wallet and start exploring!

Get Started

Core Concepts

Features

Components

Installation

System Requirements

Node.js

Package Manager

Sui Wallet

Testnet SUI

Installation Methods

Using npm

Using Yarn

Using pnpm

Dependencies

Core Dependencies

Environment Configuration

Configuration Reference

Development Server

Available Scripts

npm run dev

npm run build

npm run lint

npm run preview

Development Workflow

Project Structure

Wallet Setup

Verification

Troubleshooting

Next Steps

Quickstart Guide

Core Concepts

Integration Guide

Features

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Components

​System Requirements

Node.js

Package Manager

Sui Wallet

Testnet SUI

​Installation Methods

​Using npm

​Using Yarn

​Using pnpm

​Dependencies

​Core Dependencies

​Environment Configuration

​Configuration Reference

​Development Server

​Available Scripts

npm run dev

npm run build

npm run lint

npm run preview

​Development Workflow

​Project Structure

​Wallet Setup

​Verification

​Troubleshooting

​Next Steps

Quickstart Guide

Core Concepts

Integration Guide

Features

Build docs developers (and LLMs) love

System Requirements

Installation Methods

Using npm

Using Yarn

Using pnpm

Dependencies

Core Dependencies

Environment Configuration

Configuration Reference

Development Server

Available Scripts

Development Workflow

Project Structure

Wallet Setup

Verification

Troubleshooting

Next Steps