# Volcano Examples

This directory contains complete examples demonstrating Volcano features.

# Volcano Examples

This directory contains complete examples demonstrating Volcano features.

## Examples

### 🎯 frontend-auth-nextjs (Recommended for Frontend)

**Complete Next.js authentication application** with all Volcano auth and storage features.

**Features:**

- ✅ Email/password authentication
- ✅ Anonymous user signup and conversion
- ✅ Password recovery flow
- ✅ Email change with confirmation
- ✅ OAuth provider linking (Google, GitHub, Microsoft, Apple)
- ✅ Protected routes
- ✅ Session management
- ✅ **File storage** with upload, download, and delete
- ✅ TypeScript + Next.js 16

**Quick Start:**

```bash
cd frontend-auth-nextjs
yarn install
cp .env.example .env.local
# Edit .env.local with your Volcano credentials
yarn dev
# Open http://localhost:3001
```

**Scripts:**

- `yarn dev` - Development server
- `yarn build` - Production build
- `yarn lint` - Run linter
- `yarn type-check` - TypeScript validation

---

### 🍪 frontend-function-routes (Next.js + Function routes)

**Cookie sessions on your own origin.** A Next.js page signs users in through a
`public` HTTP function that the frontend serves at `/api/session`, and the
function keeps the tokens in `HttpOnly` cookies.

**Features:**

- Frontend Function route declared in `volcano-config.yaml`
- `__Host-` session cookies the page can't read
- CSRF token on every state change

See [frontend-function-routes](https://docs.volcano.dev/platform/examples/frontend-function-routes/README.md) and the
[Frontend Function routes guide](https://docs.volcano.dev/platform/frontends/function-routes.md).

---

### 🐍 python-data

**Python function example** showing data processing.

**Features:**

- Python runtime
- JSON request/response
- Data transformation example

---

### 📘 nodejs-hello

**Simple Hello World function** for getting started.

**Features:**

- Basic Node.js function
- Minimal example
- Perfect for first deployment

---

### 💬 realtime-chat (Next.js + Realtime)

**Minimal chat application** showing realtime messaging and presence tracking.

**Features:**

- ✅ Real-time messaging with broadcast channels
- ✅ Presence tracking - see who's online with display names
- ✅ Anonymous authentication - no account required
- ✅ User metadata - display names from signup
- ✅ In-browser configuration
- ✅ Built with Next.js 16 and Volcano SDK

**Quick Start:**

```bash
cd realtime-chat
yarn install
yarn dev
# Open http://localhost:3005
```

**What it demonstrates:**

- Anonymous signup with `display_name` metadata
- Broadcast channels for chat messages
- Presence channels to track online users
- User metadata appearing in presence events
- Symmetric visibility (late joiners see existing users)

**Note:** All SDK calls are in `app/page.tsx`; the other files render the screens.

---

## Recommended Learning Path

1. **Start Here:** `frontend-auth-nextjs`
   - Modern Next.js app with all auth features
   - Run `yarn dev` and explore all 7 pages
   - Best practices and production patterns
   - Complete authentication flows

2. **Realtime Features:** `realtime-chat`
   - See Volcano Realtime in action
   - Broadcast and presence channels
   - Anonymous auth with metadata
   - Minimal example with every SDK call in one file

## Prerequisites

Each example connects to a Volcano project. Install the CLI and create one:

```bash
npm install -g @volcano.dev/cli
volcano signup                    # create your account
volcano projects create my-app    # create a project
volcano use my-app
```

Then copy your project's API URL and anon key into the example's `.env` (see the
example's own README). New to Volcano? Start with the
[Quickstart](https://docs.volcano.dev/platform/getting-started/quickstart.md).

## Documentation

- [Authentication Guide](https://docs.volcano.dev/platform/authentication/overview.md)
- [Functions Guide](https://docs.volcano.dev/platform/functions/overview.md)
- [Database Guide](https://docs.volcano.dev/platform/databases/overview.md)
- [Storage Guide](https://docs.volcano.dev/platform/storage/overview.md)
- [SDK Reference](https://github.com/Kong/volcano-sdk-js)

## Getting Help

Each example has its own README with detailed instructions:

- [frontend-auth-nextjs/README.md](https://docs.volcano.dev/platform/examples/frontend-auth-nextjs/README.md)
- [realtime-chat/README.md](https://docs.volcano.dev/platform/examples/realtime-chat/README.md)

## License

MIT