I18n And Locale Routes
Knowledge Page Optimization
Shared Shell And Hydration
SSG And Client Only

This note records two optimization directions that may not look flashy, but are genuinely valuable:

  1. Do not attach global state machinery across the entire site
  2. Fix hydration instability first, then talk about larger performance work

1. Do not spread global state capabilities across the whole site

At the beginning, there was one common kind of waste in this project: local JSON data was static, but it was still being managed through global react-query style infrastructure.

That caused several problems:

  • pages that did not need query capabilities still paid provider cost
  • shared chunks became larger than necessary
  • the first paint had to carry more logic unrelated to the page itself

The later adjustments were:

  • local i18n JSON switched to a lighter cached reading strategy
  • QueryProvider was removed from the site-wide shared shell
  • only pages that truly need remote query capabilities mount the corresponding provider

This kind of optimization is not flashy, but it is practical.

In this round, the shared page-shell chunk dropped from about 262 KB to 233 KB, which shows that the global shell did become lighter.

2. Why hydration mismatch should be fixed early

If a page has hydration mismatch problems, the first paint is not just slower. It also becomes unstable.

These issues often do not show up as “the page is broken”, but as:

  • flickering content on first paint
  • copy or layout appearing wrong first and correct later
  • React re-rendering while taking over the DOM

In a static site, that kind of instability hurts the experience a lot.

3. Common problems handled in this project

This round fixed several common sources of hydration instability:

  • generating component IDs with random values
  • using different time values on the server and client
  • checking platform information directly during the first paint, such as whether the user is on Mac
  • visual elements initialized with randomness

The handling rules were fairly consistent:

  1. If content can be generated deterministically, do not use randomness on the first paint
  2. If information depends on the browser environment, move it into a client effect
  3. Keep the first server render and the first client render as consistent as possible