> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldhq.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Setup

> Set up SHIELD for local development

# Local Setup

Get SHIELD running locally for development and testing.

## Prerequisites

* **Node.js** 18+ (recommend using nvm)
* **npm** 9+ or **pnpm**
* **Git**
* **PostgreSQL** 14+ (local or cloud)
* **MetaMask** or other wallet with test ETH

## Quick Start

### 1. Clone the Repository

```bash theme={null}
git clone https://github.com/Babs0022/SHIELD.git
cd SHIELD
```

### 2. Install Dependencies

Root dependencies:

```bash theme={null}
npm install
```

Frontend dependencies:

```bash theme={null}
cd frontend
npm install
cd ..
```

Contract dependencies:

```bash theme={null}
cd contracts
npm install
cd ..
```

### 3. Set Up Environment

Create `.env.local` in the `frontend` directory:

```bash theme={null}
cd frontend
cp .env.example .env.local
```

Edit `.env.local`:

```env theme={null}
# Required
DATABASE_URL="postgresql://user:password@localhost:5432/shield"
PINATA_JWT="your_pinata_jwt_here"
PINATA_GATEWAY_URL="https://gateway.pinata.cloud"
NEXT_PUBLIC_SHIELD_CONTRACT_BASE_SEPOLIA="0x..."
ALCHEMY_API_KEY="your_alchemy_key"
NEXT_PUBLIC_WC_PROJECT_ID="your_walletconnect_project_id"
SESSION_SECRET="generate_a_random_32_char_string"

# Optional
NEXT_PUBLIC_APP_URL="http://localhost:3000"
```

### 4. Set Up Database

Create PostgreSQL database:

```bash theme={null}
createdb shield
```

Run migrations:

```bash theme={null}
cd frontend
npm run db:setup
```

Or manually create tables (see Database Schema docs).

### 5. Get Test ETH

For Base Sepolia:

1. Go to [Base Sepolia Faucet](https://www.alchemy.com/faucets/base-sepolia)
2. Connect your wallet
3. Request test ETH

### 6. Deploy Contracts (Optional)

For local contract testing:

```bash theme={null}
cd contracts
npx hardhat node
```

In another terminal:

```bash theme={null}
cd contracts
npx hardhat run scripts/deploy.ts --network localhost
```

Copy the deployed contract address to your `.env.local`.

### 7. Start Development Server

```bash theme={null}
cd frontend
npm run dev
```

Open [http://localhost:3000](http://localhost:3000).

## Project Structure

```
SHIELD/
├── contracts/          # Hardhat project
│   ├── contracts/      # Solidity contracts
│   ├── test/          # Contract tests
│   └── scripts/       # Deployment scripts
│
├── frontend/          # Next.js application
│   ├── src/
│   │   ├── app/       # App router
│   │   ├── components/# React components
│   │   ├── lib/       # Utilities
│   │   └── ...
│   └── public/        # Static assets
│
└── docs/             # Documentation (this!)
```

## Development Workflow

### Frontend Development

```bash theme={null}
cd frontend

# Start dev server with hot reload
npm run dev

# Run linting
npm run lint

# Type check
npx tsc --noEmit

# Build for production
npm run build
```

### Contract Development

```bash theme={null}
cd contracts

# Compile contracts
npx hardhat compile

# Run tests
npx hardhat test

# Deploy to Sepolia
npx hardhat run scripts/deploy.ts --network baseSepolia

# Verify on BaseScan
npx hardhat verify --network baseSepolia DEPLOYED_ADDRESS
```

### Testing

Run all tests:

```bash theme={null}
# Frontend tests
cd frontend
npm test

# Contract tests
cd contracts
npx hardhat test
```

## Common Issues

<AccordionGroup>
  <Accordion title="MetaMask not connecting">
    * Ensure you're on the right network (Base Sepolia for testing)
    * Reset MetaMask: Settings → Advanced → Reset Account
    * Check console for errors
  </Accordion>

  <Accordion title="Database connection errors">
    * Verify PostgreSQL is running
    * Check DATABASE\_URL format
    * Ensure database exists: `createdb shield`
  </Accordion>

  <Accordion title="Contract calls failing">
    * Verify contract address in .env
    * Ensure you have test ETH
    * Check you're on the right network
  </Accordion>

  <Accordion title="IPFS upload failing">
    * Verify PINATA\_JWT is set
    * Check JWT hasn't expired
    * Ensure file size under limit
  </Accordion>

  <Accordion title="Build errors">
    * Clear `.next` cache: `rm -rf .next`
    * Reinstall dependencies: `rm -rf node_modules && npm install`
    * Check Node version: `node --version`
  </Accordion>
</AccordionGroup>

## IDE Setup

### VS Code Extensions

Recommended extensions:

* **ESLint** - JavaScript/TypeScript linting
* **Prettier** - Code formatting
* **Solidity** - Solidity syntax highlighting
* **Tailwind CSS IntelliSense** - CSS autocomplete

### Settings

Add to `.vscode/settings.json`:

```json theme={null}
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "eslint.workingDirectories": ["./frontend", "./contracts"]
}
```

## Next Steps

* Read about [Environment Variables](/developers/environment-variables)
* Learn the [API Reference](/developers/api-reference/authentication)
* Deploy to [Vercel](/deployment/vercel)