NekoFlow/README.md

🐱 NekoFlow - Go + Next.js Monorepo

Đọc bằng tiếng Việt

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

# 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)

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

npm run build:dev

Terminal 2: Run Go server

npm run dev:go    # http://localhost:8080

After changing Next.js code:

npm run build:dev # Re-build and sync
# Go server will auto-serve new files (no restart needed)

🔨 Build

Development Build (Quick)

npm run build:dev
# → Builds Next.js + syncs to Go static folder

Production Binary

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

# Just copy and run the binary
./dist/nekoflow

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

Deploy to Linux Server

# 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)

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