Files

2025-10-08 14:57:02 +07:00

6.5 KiB

Raw Blame History

🐱 NekoFlow - Monorepo Go + Next.js

Read in English

Template monorepo sẵn có để xây dựng ứng dụng single binary kết hợp Go backend với Next.js frontend. Hoàn hảo cho các developer cần một nền tảng hiện đại, sẵn sàng production thay vì phải build từ đầu.

🎯 NekoFlow là gì?

NekoFlow là một template monorepo được dựng sẵn dành cho các developer muốn:

✅ Bắt đầu ngay lập tức thay vì mất thời gian setup boilerplate
✅ Xây dựng ứng dụng single binary (giống Gitea, nhưng cho web app)
✅ Sử dụng tech stack hiện đại (Go + Next.js + TypeScript + Tailwind)
✅ Deploy dễ dàng chỉ với một file executable
✅ Scale nhanh chóng với nền tảng vững chắc

Phù hợp cho:

Internal tools và admin dashboards
Microservices có giao diện web
Desktop applications với web UI
Prototypes và MVPs
Học tập tích hợp Go + Next.js

📦 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:

User vào http://localhost:8080
Go serve index.html (static)
Browser load HTML + React JS
React code chạy: fetch('/api/health')
Request về Go API endpoint
Go trả JSON response
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

6.5 KiB Raw Blame History