升級至 v2.3

如果您要升級在 v2 可用之前就已建立的 PWA Kit 專案，請先依照升級至 v2 指南中的說明進行操作。

Important

為了充分運用 v2.3 中提供的選擇性加入功能，特別是 react-query 整合，您必須在 PWA Kit 專案中對 _app-config/index.js、_app/index.js、package.json 進行一些變更。

對 _app-config/index.js 的變更

開啟 _app-config/index.js 並進行下列變更。

匯入啟用 react-query 並保留 getProps 支援所需的高階元件。

1- import {withLegacyGetProps} from 'pwa-kit-react-sdk/ssr/universal/components/with-legacy-get-props'
2+ import {withReactQuery} from 'pwa-kit-react-sdk/ssr/universal/components/with-react-query'

使用建議的 React Query 設定，新增 options 物件。

1// Determine whether the code is running server-side or client-side based on the presence of the window object. Set isServerSide to true if running server-side or false if running client-side.
2const isServerSide = typeof window === 'undefined'
3
4// Recommended settings for PWA-Kit usages.
5// NOTE: They will be applied server-side and client-side.
6const options = {
7  queryClientConfig: {
8    defaultOptions: {
9      queries: {
10        retry: false,
11        staleTime: 2 * 1000,
12
13        // If isServerSide is true, disable retries on mount.
14        ...(isServerSide ? {retryOnMount: false} : {})
15      },
16      mutations: {
17        retry: false
18      }
19    }
20  }
21}

更新匯出的 AppConfig 元件定義。

1- export default AppConfig
2+ export default withReactQuery(withLegacyGetProps(AppConfig), options)

對 _app/index.js 的變更

開啟 _app/index.js 並進行下列變更。

宣告一個名為 DEFAULT_LOCALE 的變數，來儲存要在應用程式中顯示訊息的預設地區設定。若是剛產生的專案，則預設訊息會以美式英文編寫。如果您尚未重新撰寫預設訊息，則 en-US 會是 DEFAULT_LOCALE 的正確值。否則，請將 DEFAULT_LOCALE 設為其他值，例如 fr-fr 或 ja-jp。

1+ const DEFAULT_LOCALE = 'en-US'

指派 DEFAULT_LOCALE 作為 targetLocale 屬性的預設值。

1- const {children, targetLocale, messages, categories: allCategories = {}} = props
2+ const {
3+     children,
4+     targetLocale = DEFAULT_LOCALE,
5+     messages = {},
6+     categories: allCategories = {}
7+ } = props

將 defaultLocale 取代為新的靜態值。

1- defaultLocale="en-US"
2+ defaultLocale={DEFAULT_LOCALE}

若啟用，useQuery 和 getProps 函式會平行執行。平行執行的副作用是，根據 getProps 的傳回值有條件地轉譯元件時，可能會導致某些 useQuery Hook 無法在伺服器上執行。為了簡單起見，我們建議您選擇 getProps 或 useQuery 來擷取資料。

Note

對 package.json 的變更

將 react-query 新增至 devDependencies。

1+ "@tanstack/react-query": "^4.0.10",

測試您的變更

若要測試您的變更是否成功，請執行以下命令：

npm install 安裝必要的 react-query 相依項目。
npm start 驗證應用程式是否能於本機執行。
npm run build 驗證建置流程是否成功。
npm run push (並透過 Runtime Admin 部署) 驗證套件部署是否成功。

進一步閱讀

若要進一步瞭解 React Query 及如何使用，請參閱 React Query 文件。