3.0 KiB

Raw Blame History

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.

Language

一律以台灣繁體中文回答使用者。
程式碼內禁止中文：comment、log、字串常數、識別字一律用英文（面向使用者的 UI 文案除外）。

Ready Set Ride

「展件互動系統」的 iPad 端控制介面。三組「電腦＋螢幕＋iPad」在展場區網內，民眾透過 iPad（PWA）操控 Unity 螢幕內容，流程結束後上傳圖片至客戶 FTPS，並以 QR Code 顯示對應圖片網址供掃描。

完整的系統架構、網路 / TLS、MQTT topic 設計、Windows 部署與開工檢查清單請見 docs/architecture.md（單一事實來源，動到部署 / MQTT / 上傳流程前先讀）。

Stack

Next.js 16 (Turbopack) + React 19，App Router，src/ 目錄。output: 'standalone'（Windows 上以 node server.js 跑，非 next start）。
Bun 為套件管理與 script runner（bun run dev / bun run build）。
PWA：@serwist/turbopack（service worker，非 @serwist/next）。
MQTT：mqtt.js over WebSocket（useMQTT hook）。
狀態：zustand + persist（裝置設定，如 station id）。
樣式：Tailwind v4 + shadcn（style base-nova，icon lucide）。
驗證：zod v4（import 為 import * as z from 'zod'）。
圖片上傳：basic-ftp（implicit FTPS）。

Commands

bun run dev — 開發伺服器
bun run build — production build
bun run lint — Biome check
bun run format — Biome format（write）

Conventions

路徑別名 @/* → ./src/*。元件 @/components、UI @/components/ui、hooks @/hooks、lib @/lib。
Biome 為唯一 formatter / linter：2 空格縮排、single quotes、import 自動排序。src/components/ui（shadcn 產出）不在 format / lint 範圍內，勿手動改它的風格。
Next.js domain rules（next / react）已在 Biome 開啟，遵守其提示。

Gotchas

src/ 目錄：所有 app code 在 src/ 下。serwist 的 swSrc 等以「專案根目錄」為基準的路徑要寫成 src/app/sw.ts，不是 app/sw.ts（後者會在 build collect page data 階段報 Could not resolve .../app/sw.ts）。
FTPS 必須跑在 Node runtime，不能用 Bun：此 FTPS server 在 data connection 上要求 TLS session resumption，Bun 不支援。涉及 src/lib/ftps.ts 的 Server Action / script 一律標 Node runtime（standalone 預設即 Node，勿標 edge）。
FTPS 設定由環境變數載入（FTP_HOST / FTP_USER / FTP_PASSWORD 必填，FTP_PORT/FTP_REMOTE_DIR/FTP_PUBLIC_BASE_URL 選填），見 loadFtpConfig()。勿把帳密寫死進程式碼。
Windows host：路徑用 path API，勿寫死 POSIX 斜線。

3.0 KiB Raw Blame History