NekoFlow/README.vi.md

🐱 NekoFlow - Monorepo Go + Next.js

Read in English

Ứng dụng single binary kết hợp Go backend với Next.js frontend.

📦 Cấu Trúc Dự Án

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

🚀 Bắt Đầu Nhanh

Yêu Cầu

• Node.js 18+
• Go 1.21+

Cài Đặt

# 1. Cài dependencies
npm install

# 2. Tùy chọn A: Dev chỉ Next.js (có hot reload)
npm run dev:web   # http://localhost:3000

# 3. Tùy chọn B: Full stack với Go
npm run build:dev # Build Next.js + sync sang Go
npm run dev:go    # Chạy Go server → http://localhost:8080

💻 Phát Triển

Phát Triển Frontend (Next.js)

npm run dev:web   # Hot reload trên port 3000

Phát Triển Full Stack (Next.js + Go)

Terminal 1: Build & sync khi sửa code Next.js

npm run build:dev

Terminal 2: Chạy Go server

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

Sau khi sửa code Next.js:

npm run build:dev # Build lại và sync
# Go server tự động serve files mới (không cần restart)

🔨 Build

Development Build (Nhanh)

npm run build:dev
# → Build Next.js + sync vào folder static của Go

Production Binary

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

Các Lệnh Có Sẵn

Lệnh	Mô Tả
npm run dev:web	Dev Next.js riêng (port 3000, hot reload)
npm run dev:go	Chạy Go server (port 8080)
npm run build:web	Build Next.js static export
npm run sync:static	Copy Next.js build → folder static của Go
npm run build:dev	Build + sync (cho development)
npm run build	Build production đầy đủ (tạo binary)

🎯 Deploy

Deploy Đơn Giản

# Chỉ cần copy và chạy binary
./dist/nekoflow

# Hoặc chỉ định port
PORT=8080 ./dist/nekoflow

Deploy Lên Linux Server

# 1. Build cho Linux
npm run build

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

# 3. Chạy trên server
ssh user@server
chmod +x /opt/nekoflow
./nekoflow

Docker (Tùy Chọn)

FROM scratch
COPY dist/nekoflow /nekoflow
ENTRYPOINT ["/nekoflow"]

🏗️ Kiến Trúc

Cách Hoạt Động

┌─────────────────────────────────────┐
│     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

❓ Câu Hỏi Thường Gặp

Đây có phải SSR (Server-Side Rendering)?

Không. Dự án này dùng Next.js Static Export (SSG - Static Site Generation).

• Next.js pre-render pages thành HTML tại thời điểm build
• Go chỉ serve static files (HTML/CSS/JS)
• React hydrate trên client-side
• API calls xảy ra client-side qua fetch()

Có thể dùng getServerSideProps?

Không. Static Export không hỗ trợ:

• getServerSideProps()
• getServerData()
• ISR (Incremental Static Regeneration)

Dùng 'use client' với useEffect() và fetch() thay thế.

Tại sao Go + Next.js?

• ✅ Single binary - Deploy dễ dàng
• ✅ Không cần Node.js runtime trong production
• ✅ Performance - Go nhanh và nhẹ
• ✅ Modern DX - React + TypeScript + Tailwind
• ✅ Cross-platform - Compile cho Linux/Mac/Windows

Kích thước binary?

Thường 10-30MB tùy thuộc:

• Kích thước code Go
• Bundle size của Next.js
• Static assets (hình ảnh, fonts)

Next.js chỉ là tool để code HTML/CSS/JS dễ hơn?

Đúng! Với Static Export:

• Next.js giúp code dễ hơn (React, TypeScript, Components)
• Build ra HTML/CSS/JS thuần
• Go chỉ serve files tĩnh
• Giống như bạn tự viết HTML/CSS/JS nhưng với DX tốt hơn

HTML của Next.js có gọi Go API?

Có! Flow hoạt động:

1. User vào http://localhost:8080
2. Go serve index.html (static)
3. Browser load HTML + React JS
4. React code chạy: fetch('/api/health')
5. Request về Go API endpoint
6. Go trả JSON response
7. React update UI

📝 License

MIT

🤝 Đóng Góp

Chào mừng mọi đóng góp! Thoải mái mở issues hoặc PRs.

---

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