Page Transition And Rendering Flow
Developmentpage-transition-and-rendering-flowPage Transition And Rendering Flow is an Agent Skill for development published in the growilabs/growi repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Auto-invoked when modifying page transition logic, global atom hydration, or the `[[...path]]` dynamic route. Explains the data flow from SSR/client navigation to page rendering, and the hydration-vs-subsequent-sync rule for global atoms (`currentPathnameAtom`, `currentUserAtom`, `isMaintenanceModeAtom`).
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/growilabs/growi/blob/HEAD/apps/app/.claude/skills/learned/page-transition-and-rendering-flow/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/page-transition-and-rendering-flow, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Page Transition and Rendering Flow
Problem
The page transition path in GROWI spans SSR, client-side navigation, URL normalization, Jotai atom hydration, and asynchronous data fetching. Changes in any one of these layers can cause subtle regressions in other layers:
- Forcing global atom updates during render causes "setState during render of a different component" warnings.
- Moving hydration into
useEffectwithout care causes flashes of stale values or hydration mismatches. - Confusing
router.asPathvsprops.currentPathnamevscurrentPathnameAtomleads to inconsistent reads across the transition.
This skill documents the intended flow so that edits preserve invariants.
Key Actors
pages/[[...path]]/index.page.tsx— Dynamic route component. Runs on server and client. Hydrates page-data atoms (currentPageDataAtom, etc.) fromgetServerSidePropsoutput.pages/[[...path]]/use-same-route-navigation.ts— Detectsrouter.asPathchanges on the client and triggersfetchCurrentPage. Always attempts fetch; actual skip is decided insideuseFetchCurrentPage.states/page/use-fetch-current-page.ts— Single source of truth for page data fetching. Decides whether a fetch is actually needed (guards against duplicate fetches by comparing decoded path / permalink ID with current atom state). Updates page-data atoms atomically on success to avoid intermediate states.pages/[[...path]]/use-shallow-routing.ts— After hydration, compares the browser URL withprops.currentPathname(the server-normalized path) and issues arouter.replace(..., { shallow: true })to align them.pages/[[...path]]/server-side-props.ts—getServerSidePropsForInitialcallsretrievePageData, performs path normalization (e.g./user/username→/user/username/), and returns data + normalizedcurrentPathnameas props.pages/_app.page.tsx/states/global/hydrate.ts— Hydrates global atoms (currentPathnameAtom,currentUserAtom,isMaintenanceModeAtom) viauseHydrateGlobalEachAtoms.
Flow 1: Server-Side Rendering (first load / reload)
- Request received: server receives request (e.g.
/user/username/memo). getServerSidePropsruns:getServerSidePropsForInitialexecutes.retrievePageDatanormalizes the path and fetches page data from the API.- Returns page data and normalized
currentPathnameas props.
- Component renders, atoms initialized:
[[...path]]/index.page.tsxreceives props and initializes page-data atoms (currentPageDataAtom, etc.).PageViewand children render on the server.
- Client-side hydration + URL alignment:
- Browser receives HTML; React hydrates.
useShallowRoutingcompares browser URL (/user/username/memo) againstprops.currentPathname(/user/username/memo/).- On mismatch,
router.replace(..., { shallow: true })silently rewrites the browser URL to the server-normalized path.
Flow 2: Client-Side Navigation (<Link> click)
- Navigation start: user clicks
<Link href="/new/page">.useRouterdetects URL change and[[...path]]/index.page.tsxre-evaluates. useSameRouteNavigationtriggers fetch:- Its
useEffectdetectsrouter.asPathchange (/new/page). - Calls
fetchCurrentPage({ path: '/new/page' }). This hook always attempts the call.
- Its
useFetchCurrentPagedecides and executes:- 3a. Path preprocessing: decodes the path; detects permalink format (e.g.
/65d4...). - 3b. Dedup guard: compares preprocessed path / extracted page ID against current Jotai state. If equal, returns without hitting the API.
- 3c. Loading flag: sets
pageLoadingAtom = true. - 3d. API call:
apiv3Get('/page', ...)with path / pageId / revisionId.
- 3a. Path preprocessing: decodes the path; detects permalink format (e.g.
- Atomic state update:
- Success: all relevant atoms (
currentPageDataAtom,currentPageEntityIdAtom,currentPageEmptyIdAtom,pageNotFoundAtom,pageLoadingAtom, …) are updated together, avoiding intermediate states wherepageIdis temporarily undefined. - Error (e.g. 404):
pageErrorAtomset,pageNotFoundAtom = true,pageLoadingAtom = falselast.
- Success: all relevant atoms (
PageViewre-renders with the new data.- Side effects: after
fetchCurrentPagecompletes,useSameRouteNavigationcallsmutateEditingMarkdownto refresh editor state.
Critical Rule: Global Atom Hydration vs Subsequent Sync
Rule: In useHydrateGlobalEachAtoms (and similar hooks that run inside _app.page.tsx), do not use useHydrateAtoms(tuples, { dangerouslyForceHydrate: true }) to keep atoms aligned with commonEachProps across navigations.
Why
useHydrateAtomsruns during render. WithdangerouslyForceHydrate: true, it re-writes atom values on every render — including navigations when props change.- Those atoms are subscribed by already-mounted components (e.g.
PageViewComponent). Writing to them mid-render triggers setState on sibling components during the parent's render, producing:Warning: Cannot update a component (
PageViewComponent) while rendering a different component (GrowiAppSubstance).
Correct pattern
Split the two concerns:
export const useHydrateGlobalEachAtoms = (commonEachProps: CommonEachProps): void => {
// 1. Initial hydration only — so children read correct values on first render
const tuples = [
createAtomTuple(currentPathnameAtom, commonEachProps.currentPathname),
createAtomTuple(currentUserAtom, commonEachProps.currentUser),
createAtomTuple(isMaintenanceModeAtom, commonEachProps.isMaintenanceMode),
];
useHydrateAtoms(tuples); // force NOT enabled
// 2. Subsequent sync (route transitions) — run after commit to avoid render-time setState
const setCurrentPathname = useSetAtom(currentPathnameAtom);
const setCurrentUser = useSetAtom(currentUserAtom);
const setIsMaintenanceMode = useSetAtom(isMaintenanceModeAtom);
useEffect(() => {
setCurrentPathname(commonEachProps.currentPathname);
}, [commonEachProps.currentPathname, setCurrentPathname]);
useEffect(() => {
setCurrentUser(commonEachProps.currentUser);
}, [commonEachProps.currentUser, setCurrentUser]);
useEffect(() => {
setIsMaintenanceMode(commonEachProps.isMaintenanceMode);
}, [commonEachProps.isMaintenanceMode, setIsMaintenanceMode]);
};
Trade-off accepted by this pattern
On a route transition, currentPathnameAtom is one render behind before the effect commits. This is safe because:
- Data fetching (
useSameRouteNavigation,useFetchCurrentPage,useShallowRouting) readsrouter.asPathorprops.currentPathnamedirectly — notcurrentPathnameAtom. useCurrentPagePathusescurrentPagePathAtom(page data) as primary and falls back tocurrentPathnameonly when the page data is absent.- Jotai's
Object.iscomparison means the effect is a no-op when the value hasn't actually changed, so setters don't need manual guards.
Source Reference Map
| Concern | File |
|---|---|
| Dynamic route entry | apps/app/src/pages/[[...path]]/index.page.tsx |
| SSR props | apps/app/src/pages/[[...path]]/server-side-props.ts |
| Route-change trigger | apps/app/src/pages/[[...path]]/use-same-route-navigation.ts |
| URL normalization | apps/app/src/pages/[[...path]]/use-shallow-routing.ts |
| Page fetch / atom updates | apps/app/src/states/page/use-fetch-current-page.ts |
| Page path selector | apps/app/src/states/page/hooks.ts (useCurrentPagePath) |
| Global atom hydration | apps/app/src/states/global/hydrate.ts |
| Global atom definitions | apps/app/src/states/global/global.ts |
| App shell | apps/app/src/pages/_app.page.tsx (GrowiAppSubstance) |
When to Apply
- Editing any hook under
states/global/that hydrates fromcommonEachProps/commonInitialProps. - Modifying
useSameRouteNavigation,useFetchCurrentPage, oruseShallowRouting. - Adding new global atoms that must stay aligned with server-side props across navigations.
- Touching
_app.page.tsxrender order or provider composition. - Debugging "setState during render of a different component" warnings originating from
_app.page.tsxorGrowiAppSubstance.
Common Pitfalls
dangerouslyForceHydrate: truefor route-sync purposes — breaks the render model. UseuseEffect+useSetAtominstead.- Moving the initial hydration into
useEffect— children reading the atom on first render would see the default (empty) value, causing flashes / hydration mismatches. - Using
currentPathnameAtomas the trigger for data fetching — the trigger isrouter.asPath, and the normalized authority isprops.currentPathname. The atom is for downstream UI consumers only. - Updating page-data atoms one-by-one during a fetch — always update atomically (success block) to avoid intermediate states visible to
PageView. - Adding a guard like
if (new !== old) set(new)for atoms — unnecessary; Jotai already dedupes onObject.is.