NekoFlow/README.md

# 🐱 NekoFlow - Go + Next.js Monorepo

[![Language](https://img.shields.io/badge/Language-English-blue)](README.md) 
[![Language](https://img.shields.io/badge/Language-Tiếng_Việt-red)](README.vi.md)

> **[Đọc bằng tiếng Việt](README.vi.md)**

A ready-to-use monorepo template for building single binary applications combining Go backend with Next.js frontend. Perfect for developers who need a modern, production-ready foundation instead of building from scratch.

## 🎯 What is NekoFlow?

NekoFlow is a **pre-built monorepo template** designed for developers who want to:

- ✅ **Start immediately** instead of spending time on boilerplate setup
- ✅ **Build single binary applications** (like Gitea, but for web apps)
- ✅ **Use modern tech stack** (Go + Next.js + TypeScript + Tailwind)
- ✅ **Deploy easily** with just one executable file
- ✅ **Scale quickly** with a solid foundation

Perfect for:
- **Internal tools** and admin dashboards
- **Microservices** with web interfaces  
- **Desktop applications** with web UI
- **Prototypes** and MVPs
- **Learning** Go + Next.js integration

## 📦 Project Structure

```
nekoflow/
├── apps/
│   ├── web/              # Next.js 14 (Frontend - Static Export)
│   └── server-go/        # Go backend + Static file server
├── scripts/              # Build scripts
└── dist/                 # Build output
```

## 🚀 Quick Start

### Prerequisites
- Node.js 18+
- Go 1.21+

### Installation

```bash
# 1. Install dependencies
npm install

# 2. Option A: Dev Next.js only (with hot reload)
npm run dev:web   # http://localhost:3000

# 3. Option B: Full stack with Go
npm run build:dev # Build Next.js + sync to Go
npm run dev:go    # Run Go server → http://localhost:8080
```

## 💻 Development

### Frontend Development (Next.js)
```bash
npm run dev:web   # Hot reload on port 3000
```

### Full Stack Development (Next.js + Go)

**Terminal 1: Build & sync when you change Next.js code**
```bash
npm run build:dev
```

**Terminal 2: Run Go server**
```bash
npm run dev:go    # http://localhost:8080
```

**After changing Next.js code:**
```bash
npm run build:dev # Re-build and sync
# Go server will auto-serve new files (no restart needed)
```

## 🔨 Build

### Development Build (Quick)
```bash
npm run build:dev
# → Builds Next.js + syncs to Go static folder
```

### Production Binary
```bash
npm run build
# → Builds Next.js + Go binary
# → Output: dist/nekoflow (single binary ~10-30MB)
```

### Available Commands

| Command | Description |
|---------|-------------|
| `npm run dev:web` | Dev Next.js only (port 3000, hot reload) |
| `npm run dev:go` | Run Go server (port 8080) |
| `npm run build:web` | Build Next.js static export |
| `npm run sync:static` | Copy Next.js build → Go static folder |
| `npm run build:dev` | Build + sync (for development) |
| `npm run build` | Full production build (creates binary) |

## 🎯 Deploy

### Simple Deployment
```bash
# Just copy and run the binary
./dist/nekoflow

# Or specify port
PORT=8080 ./dist/nekoflow
```

### Deploy to Linux Server
```bash
# 1. Build for Linux
npm run build

# 2. Upload
scp dist/nekoflow-linux user@server:/opt/nekoflow

# 3. Run on server
ssh user@server
chmod +x /opt/nekoflow
./nekoflow
```

### Docker (Optional)
```dockerfile
FROM scratch
COPY dist/nekoflow /nekoflow
ENTRYPOINT ["/nekoflow"]
```

## 🏗️ Architecture

### How It Works

```
┌─────────────────────────────────────┐
│     Single Binary (nekoflow)        │
│                                     │
│  ┌────────────┐   ┌──────────────┐ │
│  │ Go Server  │   │ Static Files │ │
│  │            │   │ (Next.js)    │ │
│  │ - API      │   │ - HTML       │ │
│  │ - Router   │   │ - CSS        │ │
│  │ - Embedded │   │ - JS         │ │
│  └────────────┘   └──────────────┘ │
└─────────────────────────────────────┘
         ↓
    Single Port (8080)
         ↓
   ┌─────────────┐
   │  Browser    │
   │  - UI       │
   │  - API call │
   └─────────────┘
```

### Tech Stack

**Frontend:**
- Next.js 14 (Static Export)
- React 18
- TypeScript
- Tailwind CSS

**Backend:**
- Go 1.21+
- gorilla/mux (Router)
- embed (Static files)

**Build:**
- npm workspaces
- Bash scripts
- Go build

## ❓ FAQ

### Is this SSR (Server-Side Rendering)?
**No.** This uses Next.js **Static Export** (SSG - Static Site Generation).
- Next.js pre-renders pages to HTML at build time
- Go only serves static files (HTML/CSS/JS)
- React hydrates on the client-side
- API calls happen client-side via `fetch()`

### Can I use getServerSideProps?
**No.** Static Export doesn't support:
- `getServerSideProps()`
- `getServerData()`
- ISR (Incremental Static Regeneration)

Use `'use client'` with `useEffect()` and `fetch()` instead.

### Why Go + Next.js?
- ✅ **Single binary** - Easy deployment
- ✅ **No Node.js runtime** needed in production
- ✅ **Performance** - Go is fast and lightweight
- ✅ **Modern DX** - React + TypeScript + Tailwind
- ✅ **Cross-platform** - Compile for Linux/Mac/Windows

### Binary size?
Typically **10-30MB** depending on:
- Go code size
- Next.js bundle size
- Static assets (images, fonts)

## 📝 License

MIT

## 🤝 Contributing

Contributions welcome! Feel free to open issues or PRs.

---

**Built with ❤️ using Go + Next.js + TypeScript**