TL;DR

  • sc-datav là repo cá nhân của knight-L, public 11/2025, đến nay đã 1.082 sao và 280 fork, license Apache 2.0.

  • Bốn dashboard 3D xoay quanh bản đồ, build trên React 19.1 + Three.js 0.183 + @react-three/fiber 9.4 + ECharts 6 + Vite 8 (Rolldown).

  • Code tách rõ map/ (3D scene), panel/ (charts), stores/ (zustand) - dễ thay bản đồ Việt Nam, dễ reuse từng component.

  • Đi kèm repo phụ sat-hunter để tải tile vệ tinh làm displacement và normal map cho terrain.

  • Hợp với ai muốn build dashboard cho tỉnh thành, khu công nghiệp, sân bay hay nhà máy mà không phải dựng lại nền 3D từ đầu.

Demo 0 - bản đồ 3D dạng vệ tinh kèm panel biểu đồ kinh tế

Vì sao một repo cá nhân lại đáng xem

Trên GitHub có hàng trăm dashboard "datav-style" (kiểu Alibaba DataV), nhưng phần lớn dừng lại ở Vue 2 hoặc React 16 với Three.js phiên bản đời 2022. sc-datav đi ngược dòng đó: nó dựng lại toàn bộ stack ở mức mới nhất.

Số liệu thực tế lúc viết bài: 1.082 sao, 280 fork chỉ sau khoảng bảy tháng. Đó là tỉ lệ cao bất thường cho một repo cá nhân của lập trình viên không nổi tiếng, và là tín hiệu thị trường rõ: rất nhiều team đang cần một bản tham chiếu "3D map dashboard hiện đại" để fork hơn là tự dựng.

Bóc tách stack: từ React 19 đến shader material

Dependency được khai báo trong package.json chính xác như sau:

Lưu ý: badge trên README ghi Three.js 0.181.2 nhưng package.json đang ở 0.183.2. Khi fork về thì đọc thẳng package.json cho đỡ nhầm.

Bốn demo, bốn flavor

Cấu trúc src/pages/Demo*/ đi theo một pattern thống nhất: index.tsx là layout, thư mục map/ chứa Three.js scene, thư mục panel/ chứa ECharts widget, thư mục stores/ giữ state riêng bằng zustand. Nhờ vậy bốn demo không bị dính nhau và có thể tách riêng từng cái.

  • Demo 0 - 经济运行监测: map vệ tinh tone tối, bốn panel chart kinh tế (line, bar, table). Gồm baseMap, outline, flyLine (đường bay) và lights. Bản này dễ học nhất vì gần với pattern "map + chart panels" truyền thống.

  • Demo 1 - 智慧城市数据大脑: tone cam sáng, bản đồ cấp huyện với heatmap dày đặc, 6 panel chart. Có riêng cloud, heatmap, label, tooltip, bar 3D, kèm cityData.ts và một loading.tsx riêng. Đây là demo nặng nhất, đáng đọc nếu bạn muốn học cách layer nhiều hiệu ứng trên cùng một scene.

  • Demo 2 - 电力全景感知平台: tone xanh navy kiểu sci-fi, có beamLight (cột sáng dựng đứng), cone, geoTrail (vệt vẽ theo geo path), mirror (phản chiếu) và shaderMaterial với GLSL custom. Đây là chỗ để học pattern shader trong R3F.

  • Demo 3: chỉ có model.tsx, render một mô hình động cơ phản lực với FPS counter - dùng để benchmark render performance, không phải dashboard thực tế.

Demo 1 - heatmap thành phố với chỉ số doanh nghiệp

Demo 2 - power grid với beamLight và shader material

Chạy thử trong 5 phút

Yêu cầu Node 18 trở lên và pnpm 8 trở lên (Vite 8 Rolldown thực ra hoạt động ổn với Node 20 LTS hoặc 22).

git clone https://github.com/knight-L/sc-datav.git
cd sc-datav
pnpm install
pnpm dev

Mở http://localhost:5173/#/demo0 đến #/demo3 để xem từng dashboard. Build production bằng pnpm build, preview bằng pnpm preview.

Không muốn tự cài thì xem live demo: knight-l.github.io/sc-datav

Thay bằng bản đồ Việt như thế nào

Cốt lõi nằm ở hai file trong src/assets/:

  • sc.json - GeoJSON ranh giới hành chính cấp tỉnh và huyện.

  • sc_outline.json - đường biên ngoài để vẽ flyline và glow.

Để chuyển sang Việt Nam, lấy GeoJSON tỉnh thành VN từ các nguồn mở (OSM, dữ liệu Cục Đo đạc), convert về cùng schema rồi thay hai file trên. Texture terrain (sc_displacement_map.png, sc_normal_map.png) thì dùng tool đi kèm sat-hunter để tải tile vệ tinh khu vực cần, sau đó bake displacement và normal trong Blender hoặc Photoshop.

Component reuse được độc lập: flyLine.tsx, beamLight.tsx, heatmap.tsx, shaderMaterial.tsx đều nhận props rời, không hard-code Tứ Xuyên - bạn có thể copy nguyên một component vào dự án khác.

Hạn chế thực tế

  • Không có test, không Storybook; code style hơi ad-hoc giữa các demo nên đọc từng demo riêng, đừng kỳ vọng một design system thống nhất.

  • Performance phụ thuộc GPU client. Three.js cộng @react-three/postprocessing không nhẹ; máy yếu hoặc laptop tích hợp sẽ tụt FPS khi mở Demo 1 hoặc Demo 2.

  • Demo 3 cần asset ngoài (mô hình động cơ), repo không kèm rõ ràng nên build có thể warning về asset thiếu.

  • License Apache 2.0: thoải mái cho commercial, nhưng phải giữ NOTICE và attribution.

Khi nào nên fork, khi nào không

Nên fork khi: bạn cần một dashboard 3D nội bộ cho cảng, sân bay, mạng lưới điện, khu công nghiệp, hoặc chỉ đơn giản là muốn học stack React 19 và R3F 9 qua một codebase thực tế đã chạy production-like.

Không nên fork khi: bạn cần một white-label dashboard có theme system, dark/light toggle, i18n và support team - sc-datav là showcase, không phải sản phẩm có roadmap dài hạn. Trong trường hợp đó, build từ đầu với cùng stack sẽ kiểm soát tốt hơn.

Kết

sc-datav là một trong số ít repo dataviz 3D dùng React 19 và Three.js mới đến vậy, lại còn mở Apache 2.0. Với người đã quen R3F, đây là tài liệu tham khảo trực quan; với người mới, đây là chỗ tốt để xem một dashboard 3D "trông pro" được dựng như thế nào trước khi viết bản của riêng mình.

References