# React 專案建置 2025

Elantris

[TOC]

---

## 前言

紀錄一下自己在這個時間點 (2025) 開一個新專案時選用的工具技術與步驟，目前主要都是在寫網頁前端，目標放在能夠產出靜態網頁的開發環境。

## 專案環境

- Node.js LTS (v22)
- NPM (v11)
- Build Tool: Vite (v6)
- template: react-ts
- CI
- [simple-git-hooks](https://github.com/toplenboren/simple-git-hooks) (v2)
- [Prettier](https://github.com/prettier/prettier) (v3)
- [pretty-quick](https://github.com/prettier/pretty-quick) (v4)
- [husky](https://github.com/typicode/husky)
- Theming
- [Tailwind](https://tailwindcss.com/) CSS (v4)
- [Sass](https://sass-lang.com/)
- Routing
- [Wouter](https://github.com/molefrog/wouter) (v3)
- [TanStack Router](https://github.com/TanStack/router)
- Data Fetching
- [Axios](https://github.com/axios/axios)
- [TanStack Query](https://github.com/tanstack/query/)
- State Management
- [Jotai](https://github.com/pmndrs/jotai)
- [Zustand](https://github.com/pmndrs/zustand)
- [Redux](https://github.com/reduxjs/redux) or [Redux Toolkit](https://github.com/reduxjs/redux-toolkit)

## 安裝步驟

### 1. 專案環境

[Vite](https://vite.dev/guide/) React + TypeScript 預設配置就足以應付靜態網站基本需求

npm create vite@latest

### 2. CI 相關

[Prettier](https://prettier.io/docs/install) 一致的程式碼排版，照自己的習慣走

[pretty-quick](https://github.com/prettier/pretty-quick) + [simple-git-hooks](https://github.com/toplenboren/simple-git-hooks) 確保每個 commit 都有遵守排版規則

Prettier Plugins
- [prettier-plugin-organize-imports](https://github.com/simonhaenisch/prettier-plugin-organize-imports) 排版每個模組的引入
- [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss) 排版 tailwind utility class

// package.json
{
  "scripts": {
    "format": "pretty-quick",
    "format:all": "prettier --write ."
  },
  "prettier": {
    "printWidth": 120,
    "semi": false,
    "singleQuote": true,
    "plugins": [
      "prettier-plugin-organize-imports",
      "prettier-plugin-tailwindcss"
    ]
  },
  "simple-git-hooks": {
    "pre-commit": "npx pretty-quick --staged"
  }
}

### 3. 樣式相關

網頁專案通常最注重自訂樣式開發，如果是開發使用者最常接觸的前台互動介面，那終極目標就是寫出一個「元件庫」(Component Library) 等級的樣式，以利後續開發時可以直接取用、實作流程以維持團隊一致的風格與重複的互動邏輯。

目前能夠寫樣式的方法非常多，無論是 Vanilla CSS、Pre-processors、CSS-in-JS、CSS Framework、Utility CSS、...

如何管理是前端工程師的一大考驗，同時兼顧可讀性、擴充性、團隊協作是艱鉅的挑戰，目前我看過好幾個專案依然是四散各地的程式碼、每個元件各自為政。

我會傾向在開站之初先訂好規範，主要區分幾個重點項目：Reset、Theme、Layout、Component 四大類別：

- Reset
- [Normalize.css](https://necolas.github.io/normalize.css/) 我最常用的套件，讓個瀏覽器有相同的基底
- [Tailwind Preflight](https://tailwindcss.com/docs/preflight) 如果專案使用 Tailwind 時預設會用
- 覆寫元件庫，如果專案是以某個 component library 為基底，我會特別開一個檔案統整影響全站的覆寫樣式
- Theme
- 主要放一些變數，顏色、間距、字型、陰影、邊框等全站主題風格
- Layout
- 一個網站通常以「頁面」為單位提供對應服務，跨頁面的元件適合獨立出來討論
- 常見的元件為 Header、Footer、Nav Bar、Nav Drawer、Section 等
- 例如頁面要以 100vh, 100vw 來管理或是維持 overflow 自然捲動等
- Component
- 最常變動的項目，目標是以 scoped 為主，盡量不影響其他元件，把屬於自己的樣式關在元件內

每年都有所謂的 Best CSS Frameworks 文章看看就好，挑一個喜歡的來當作基底作修改即可。

如果是高度客製化的情境我會選用 Sass 或 Tailwind 為主體，兩種截然不同的管理風格有時也會混用，Vite 環境也都能輕鬆安裝。

- [CSS Pre-processors](https://vite.dev/guide/features#css-pre-processors)
- [Get started with Tailwind CSS](https://tailwindcss.com/docs/installation/using-vite)

### 4. 第三方套件

React 有相當完整的生態系，舉凡 routing、state management、Data Fetching、... 不斷有後起之秀挑戰老牌地位，雖然每一個套件都有各自的調性，理論上只要官方文件有持續在維護，身為一名專業的前端工程師就該能串接使用。

不過比起不斷地安裝套件，有時候我也會比較傾向用原生的語法來撰寫，例如 Fetch API 取代 axios；或是 React 本身提供的功能，例如 Context API 取代 redux 等中央狀態管理套件。畢竟遇到一直 breaking change 的套件更新 migrate 起來也是非常累人。