227 lines
5.6 KiB
Markdown
227 lines
5.6 KiB
Markdown
# 🐱 NekoFlow - Monorepo Go + Next.js
|
|
|
|
[](README.md)
|
|
[](README.vi.md)
|
|
|
|
> **[Read in English](README.md)**
|
|
|
|
Ứ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
|
|
|
|
```bash
|
|
# 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)
|
|
```bash
|
|
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**
|
|
```bash
|
|
npm run build:dev
|
|
```
|
|
|
|
**Terminal 2: Chạy Go server**
|
|
```bash
|
|
npm run dev:go # http://localhost:8080
|
|
```
|
|
|
|
**Sau khi sửa code Next.js:**
|
|
```bash
|
|
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)
|
|
```bash
|
|
npm run build:dev
|
|
# → Build Next.js + sync vào folder static của Go
|
|
```
|
|
|
|
### Production Binary
|
|
```bash
|
|
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
|
|
```bash
|
|
# Chỉ cần copy và chạy binary
|
|
./dist/nekoflow
|
|
|
|
# Hoặc chỉ định port
|
|
PORT=8080 ./dist/nekoflow
|
|
```
|
|
|
|
### Deploy Lên Linux Server
|
|
```bash
|
|
# 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)
|
|
```dockerfile
|
|
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**
|
|
|