Remix Blues Stack

深入了解 Remix Stacks。

npx create-remix@latest --template remix-run/blues-stack

Stack 的內容

• 使用 Docker 進行多區域 Fly 應用程式部署
• 多區域 Fly PostgreSQL 集群
• 用於 Fly 備份區域故障轉移的健康檢查端點
• 使用 GitHub Actions 在合併到生產和預備環境時進行部署
• 使用 基於 Cookie 的會話進行電子郵件/密碼身份驗證
• 使用 Prisma 進行資料庫 ORM
• 使用 Tailwind 進行樣式設計
• 使用 Cypress 進行端對端測試
• 使用 MSW 進行本地第三方請求模擬
• 使用 Vitest 和 Testing Library 進行單元測試
• 使用 Prettier 進行程式碼格式化
• 使用 ESLint 進行程式碼檢查
• 使用 TypeScript 進行靜態類型檢查

不喜歡 stack 中的某些部分？ Fork 它、修改它，然後使用 npx create-remix --template your/repo！ 讓它成為你自己的。

快速開始

點擊此按鈕以使用專案設定、啟動的 Postgres 和預先安裝的 Fly 建立 Gitpod 工作區

開發

• 首先執行此 stack 的 remix.init 腳本，並提交它對專案所做的變更。

  npx remix init
  git init # if you haven't already
  git add .
  git commit -m "Initialize project"
  

• 在 Docker 中啟動 Postgres 資料庫

  npm run docker
  

  注意：npm 腳本將在 Docker 在背景設定容器時完成。在繼續之前，請確保 Docker 已完成且您的容器正在運行。

• 初始設定

  npm run setup
  

• 執行第一次建置

  npm run build
  

• 啟動開發伺服器

  npm run dev
  

這將在開發模式下啟動您的應用程式，並在檔案變更時重新建置資源。

資料庫種子腳本會建立一個新用戶，其中包含一些可用於開始使用的資料

• 電子郵件：rachel@remix.run
• 密碼：racheliscool

如果您不想使用 Docker，您也可以使用 Fly 的 Wireguard VPN 連接到開發資料庫（甚至是您的生產資料庫）。您可以在此處找到設定 Wireguard 的說明，並在此處找到建立開發資料庫的說明。

相關程式碼

這是一個相當簡單的筆記應用程式，但它是一個很好的範例，說明如何使用 Prisma 和 Remix 建置完整的 stack 應用程式。主要功能是建立使用者、登入和登出，以及建立和刪除筆記。

• 建立使用者、登入和登出 ./app/models/user.server.ts
• 使用者會話以及驗證它們 ./app/session.server.ts
• 建立和刪除筆記 ./app/models/note.server.ts

部署

此 Remix Stack 附帶兩個 GitHub Actions，可自動處理將您的應用程式部署到生產和預備環境。

在您第一次部署之前，您需要做一些事情

• 安裝 Fly

• 註冊並登入 Fly

  fly auth signup
  

  注意：如果您有多個 Fly 帳戶，請確保您在 Fly CLI 中登入的帳戶與您在瀏覽器中登入的帳戶相同。在您的終端機中，執行 fly auth whoami 並確保電子郵件與登入瀏覽器的 Fly 帳戶相符。

• 在 Fly 上建立兩個應用程式，一個用於預備環境，一個用於生產環境

  fly apps create blues-stack-template
  fly apps create blues-stack-template-staging
  

  注意：成功建立應用程式後，請仔細檢查 fly.toml 檔案，以確保 app 金鑰是您建立的生產應用程式的名稱。此 Stack 會在初始化時自動附加一個唯一的後綴，這可能與您在 Fly 上建立的應用程式不符。如果您有此不符，您可能會在 Github Actions CI 記錄中看到 404 錯誤。

• 初始化 Git。

  git init
  

• 建立新的 GitHub 儲存庫，然後將其新增為專案的遠端。暫時不要推送您的應用程式！

  git remote add origin <ORIGIN_URL>
  

• 將 FLY_API_TOKEN 新增至您的 GitHub 儲存庫。為此，請前往 Fly 上的使用者設定並建立新的 權杖，然後使用名稱 FLY_API_TOKEN 將其新增至 您的儲存庫機密。

• 將 SESSION_SECRET 新增至您的 Fly 應用程式機密，為此，您可以執行以下命令

  fly secrets set SESSION_SECRET=$(openssl rand -hex 32) --app blues-stack-template
  fly secrets set SESSION_SECRET=$(openssl rand -hex 32) --app blues-stack-template-staging
  

  注意：建立預備機密時，您可能會從 Fly CLI 收到類似以下的警告

  WARN app flag 'blues-stack-template-staging' does not match app name in config file 'blues-stack-template'
  

  這僅表示目前的目錄包含一個引用我們在第一步中建立的生產應用程式的設定。忽略此警告並繼續建立機密。

  如果您沒有安裝 openssl，您也可以使用 1password 來產生隨機機密，只需將 $(openssl rand -hex 32) 替換為產生的機密即可。

• 為您的預備和生產環境建立資料庫。執行以下操作

  fly postgres create --name blues-stack-template-db
  fly postgres attach --app blues-stack-template blues-stack-template-db
  
  fly postgres create --name blues-stack-template-staging-db
  fly postgres attach --app blues-stack-template-staging blues-stack-template-staging-db
  

  注意：當您在上面的 fly set secret 步驟中附加預備資料庫時，您會因相同的原因收到相同的警告。別擔心。繼續！

Fly 會負責為您設定 DATABASE_URL 機密。

現在一切都設定好了，您可以提交並將您的變更推送至您的儲存庫。每次提交到您的 main 分支都會觸發部署到您的生產環境，而每次提交到您的 dev 分支都會觸發部署到您的預備環境。

如果您在部署到 Fly 時遇到任何問題，請確保您已遵循上述所有步驟，如果您已遵循，請將您部署的盡可能多的詳細資訊（包括您的應用程式名稱）發佈到 Fly 支援社群。他們通常在那裡的回應速度很快，並且希望能夠協助解決您的任何部署問題和疑問。

多區域部署

當您的網站和資料庫在單一區域中運行後，您可以按照 Fly 的擴展和 多區域 PostgreSQL 文件來新增更多區域。

請務必為您的應用程式設定 PRIMARY_REGION 環境變數。您可以使用 fly.toml 中的 [env] 設定，將其設定為您想要用作應用程式和資料庫主要區域的區域。

在其他區域測試您的應用程式

安裝 ModHeader 瀏覽器擴充功能（或類似的擴充功能），並使用它載入您的應用程式，其中標頭 fly-prefer-region 設定為您想要測試的區域名稱。

您可以檢查回應中的 x-fly-region 標頭，以了解您的請求由哪個區域處理。

GitHub Actions

我們使用 GitHub Actions 進行持續整合和部署。進入 main 分支的任何內容都會在執行測試/建置等之後部署到生產環境。dev 分支中的任何內容都會部署到預備環境。

測試

Cypress

我們在此專案中使用 Cypress 進行端對端測試。您會在 cypress 目錄中找到這些測試。當您進行變更時，請新增到現有檔案或在 cypress/e2e 目錄中建立新檔案，以測試您的變更。

我們使用 @testing-library/cypress 以語義方式選取頁面上的元素。

若要在開發中執行這些測試，請執行 npm run test:e2e:dev，這會啟動應用程式的開發伺服器以及 Cypress 用戶端。請確保資料庫如上所述在 Docker 中執行。

我們有一個實用工具，可用於測試已驗證的功能，而無需經歷登入流程

cy.login();
// you are now logged in as a new user

我們還有一個實用工具可以在測試結束時自動刪除使用者。只需確保在每個測試檔案中新增此工具即可

afterEach(() => {
  cy.cleanupUser();
});

這樣，我們可以保持您的本地資料庫乾淨，並保持您的測試彼此隔離。

Vitest

對於公用程式和個別元件的較低層級測試，我們使用 vitest。我們透過 @testing-library/jest-dom 擁有特定於 DOM 的判斷提示協助程式。

類型檢查

此專案使用 TypeScript。建議為您的編輯器設定 TypeScript，以獲得非常好的編輯器內體驗，包括類型檢查和自動完成。若要在整個專案中執行類型檢查，請執行 npm run typecheck。

程式碼檢查

此專案使用 ESLint 進行程式碼檢查。這是在 .eslintrc.js 中設定的。

格式化

我們在此專案中使用 Prettier 進行自動格式化。建議安裝編輯器外掛程式（例如 VSCode Prettier 外掛程式），以在儲存時取得自動格式化。還有一個 npm run format 腳本，您可以執行該腳本來格式化專案中的所有檔案。