readr-nuxt

本專案採用 Nuxt.js 的伺服端渲染（Server Side Rendering），又稱同構渲染（Universal Rendering）。

如何開始？

先決條件：
- 安裝套件管理器 Yarn。
- 確保 Node.js 版本在 14 以上。由於不同專案對於 Node 會有不同要求，你可能需要 Node 版本管理器。你可以安裝知名的 nvm，也可以試試看我覺得更好用的 n。
在 yarn install 之前，你身上要有 config：
- config 放在本專案根目錄的 configs 資料夾，裡面有一個 config.sample.js，但那是假的，真正的 config 非常機密，絕對不能上傳到 GitHub 上。雖然我們已經在 .gitignore 指定忽視這些檔案，但仍請你務必小心。
- 那 config 要跟誰拿？有兩種方法：
  1. 如果你已經可以登入本公司所使用的雲端服務 GCP（Google Cloud Platform），那進到 Home/Dashboard，點擊左上角的三條槓槓選單，找到 Source Repositories，點下去，你會進到一個擁有許多 repositories 的頁面。config 有分正式機和測試機，在本地（local）端開發需要測試機的 config。點選名字為 configs 的 repo，進去後，依循 readr-media/readr-nuxt/dev 的路徑，你會看到裡頭有三份檔案 config.js、credentials.json 和 token.json。由於這份教學文件會過時，若檔案數量或名稱不符，你不確定自己要哪幾份檔案，可以問其他前端工程師。但就目前的情況，這三個檔案你都要下載，至於要怎麼下載，可以看這份文件。如果你不想一開始就花這麼多時間，可以直接複製貼上檔案內的程式碼，也可以試試第二種方法（不過你未來總是要知道如何操作 Cloud Source Repositories，比如當你要更新 config 時，現在先了解也無妨）。
  2. 直接跟有 config 的工程師拿。
- 拿到 config 後，注意 config.js 中的 ENV 是不是 'local'；若不是，請改成 'local'（ENV 是拿來區分本地、測試（dev）和正式（prod）環境的變數）。
- 把 config 全丟進 configs 資料夾。
在終端機輸入 yarn install。
安裝完套件後，輸入 yarn dev，等它構建完，會有一個 Server listening on XXX 的指示，將 XXX 輸進瀏覽器的網址列，Enter，你就能看見 READr 囉！

資料夾結構

├── apollo/
│   └── queries/
├── assets/
│   ├── css/
│   └── imgs/
│       └── report/
├── components/
│   ├── app/
│   ├── helpers/
│   ├── report/
│   └── shared/
├── configs/
├── helpers/
├── layouts/
├── middleware/
├── pages/
├── plugins/
│   └── vue-plugins/
├── server/
├── server-middleware/
│   └── apis/
├── static/
└── store/

有很多資料夾是 Nuxt 自動創建的，我會建議你至少看過 Nuxt 官方對各個資料夾的解說。底下，我會針對每個資料夾做一簡要的說明。

部署

採用 Drone 自動化部署，設定寫在 .drone.yml。注意 getDevConfig 和 getProdConfig，drone 會在這兩個步驟去拿儲存在 Cloud Source Repositories 的 config，其中可看見 drone 拿 config 的路徑（cp -R source destination）和觸發此步驟的時機（when）。

當你將 commit 推到 dev 分支，drone 會開始構建專案，並在構建完後更新測試機（你會在 Slack 的 jenkins 頻道看見通知）。

若要將專案推到正式機，須經 PM（產品經理）確認，再從 dev 分支發 PR（pull request）合併（merge）到 master 分支，drone 便會開始構建專案。構建完後，需通知後端該部署哪一版本的專案（版本可從 jenkins 頻道的訊息得知）。部署完後，正式機便更新了。

命名規範

components 資料夾的元件名稱一率採用 UpperCamelCase。其它資料夾與檔案，除非有特殊原因，不然一率採用 kebab-case。

盡可能使用具名導入，以利 tree shaking。使用具名導入時，可能會使變數來源變得不清，此時建議加上以被導入的套件為名的前綴，比如：

import { get as axiosGet } from 'axios'

若套件名有多個單字，可考慮將其全部連起小寫，以利識別實際導出的變數名：

import { get as jscookieGet } from 'js-cookie'

Git 開發流程

採用 GitHub flow。

你應該時時與 dev 分支上的程式碼同步，至少每次推 commit 或發 PR 到 dev 前，都要先 git pull -r upstream dev，盡早在本地解決衝突。

Git Commit 訊息規範

遵守 Angular 製定的 commit 訊息規範。

若找不到適合的 type，可用 chore。

關於如何選擇正確的 type，除了符合 Angular 對該 type 的定義，也可以想：未來的開發者該以什麼樣的態度來理解這段紀錄？

若是 fix，就代表這次修改是要解決一個錯誤，那開發者就要找出錯誤在哪裡；若是 refactor，就代表這次修改不會影響任何程式可見的外部行為，開發者可以專注於重構手法；若是 style，就代表這次修改與程式碼風格有關，開發者若是在找某個功能是怎麼演變的，便可以跳過這個 commit。

換言之，一個好的 type（或更廣泛來說，一個好的 commit 訊息、好的 commit 紀錄），可以讓開發者更快速地理解這次修改是在做什麼，並把注意力投注在正確的地方。

關於如何撰寫一個好的 commit 訊息，可參考這篇文章。

瀏覽器兼容

支援 READr 訪客使用率 >= 0.05% 的瀏覽器。

如何知道瀏覽器使用率？用 Can I use 網站分析 READr 的 GA（Google Analytics）資料，看在 2019/07/13 到 2020/07/13 這一年間進到 READr 官網的訪客（visitors）用了哪些瀏覽器。

獲取分析後，先使用 browserslist defaults（> 0.5%, last 2 versions, Firefox ESR, not dead），再透過以下設定覆蓋：

IE 11 = 0.01%，不支援 IE。
Edge 18 = 0.43%，支援 Edge >= 18。
Chrome 49 = 0.09%，支援 Chrome >= 49。
Firefox 71 = 0.2%，支援 Firefox >= 71。
Safari 12.1 = 0.1%，支援 Safari >= 12.1。
Safari & Chrome for iOS 10.0-10.2 = 0.08%，支援 iOS >= 10.0。
Samsung Internet 9.2 = 0.13%，支援 Samsung >= 9.2。
Opera 46 for Android = 0.05%、Opera 65 = 0.09，支援 Opera >= 46。
Opera Mobile 12 = 0.05%，支援 OperaMobile >= 12。
Android browser 資料不足，使用 defaults。
Chrome for Android 資料不足，使用 defaults。

將設定寫在 .browserslistrc（針對 CSS）和 nuxt.config.js 的 build.babel.presets（針對 JS）。

kwhsiung / readr-nuxt

readr-nuxt

如何開始？

資料夾結構

apollo 資料夾

assets 資料夾

components 資料夾

configs 資料夾

helpers 資料夾

layouts 資料夾

middleware 資料夾

pages 資料夾

plugins 資料夾

server 資料夾

server-middleware 資料夾

static 資料夾

store 資料夾

部署

命名規範

Git 開發流程

Git Commit 訊息規範

瀏覽器兼容

About

Languages