The three layers
- HTMLWhat is on the page: headings, buttons, images and lists.
- CSSHow it looks: layout, colour, spacing and type.
- JavaScriptWhat it does: clicks, requests and page changes.
React, Next.js, Tailwind and @pw-tech/omni-ui sit on top of these three.
The one idea
UI = f(state)
Change the data and the framework redraws the screen. If two values must agree, derive one from the other instead of storing two copies. Stored copies drift; derived values cannot.
Who writes the HTML?
| Model | Analogy | Built by | SEO | Freshness |
|---|---|---|---|---|
| CSR | Raw ingredients delivered to your house. You cook. | Browser | Risky | Always live |
| SSR | Restaurant cooks fresh when you order. | Server, per request | Good | Always live |
| SSG | The thali was made this morning. Grab and go. | Build, once | Good | Frozen at build |
| ISR | Ready thali, remade when older than a limit. | Build plus occasional server work | Good | Stale by at most N seconds |
Hydration is when JavaScript makes the server-rendered page interactive. Before it arrives, the page can look ready while its buttons do nothing.
View Source shows what the server sent. Elements shows what exists now. They are different views of the page.
The DOM
HTML is the recipe. The DOM is the dish: a live tree the browser builds from the HTML. JavaScript searches and changes this tree.
The browser can repair broken HTML by closing tags, adding a tbody, or splitting invalid nesting. That is another reason View Source and Elements can differ.
| Change | Analogy | Browser work |
|---|---|---|
| Colour, background, shadow | Repaint a wall | Style, then paint |
| Width, height, margin, font size | Resize furniture | Style, layout, then paint |
transform, opacity | Slide a sticker on glass | Composite only |
For smooth animation, prefer transform and opacity.
SEO and visibility
Googlebot crawls a URL, renders the page, decides whether to index it, then ranks it. Crawling and indexing are different steps.
| Control | What it does | What it does not do |
|---|---|---|
robots.txt Disallow | Asks polite bots not to crawl a path. | Hide the URL, secure a page, or let Google read its noindex rule. |
noindex | Asks search engines not to show the page in results. | Work if crawling is blocked. |
nofollow | Asks bots not to follow links from a page. | Hide the page itself. |
| Login | Actually restricts access to the page. | Replace a search directive on a public page. |
| Canonical | Hints which URL is the preferred version. | Force Google to use that URL. |
Classic mistake: combine Disallow and noindex. Google cannot fetch the page to read noindex, so the URL may remain indexed as blocked.
For non-production: put login in front, send X-Robots-Tag: noindex, nofollow on every response, set the root layout to noindex, and do not block crawling in robots.txt.
Release checks
curl -sI https://<staging-domain> | grep -i x-robots-tag
curl -sI https://www.pw.live | grep -i x-robots-tag
The staging response must say noindex. Production should print nothing.
See what Google sees
Use Search Console URL Inspection, Rich Results Test, DevTools with JavaScript disabled, or a site:yourdomain.com search.
Six useful DevTools moves
| Tab | Question |
|---|---|
| Elements | Why does it look like that? A struck-through rule lost. |
| Console | Is something red? Include the error in the bug report. |
| Network | Did the browser request the right data? |
| Throttling | Does it still work on Slow 4G and a slower CPU? |
| Device toolbar | Does it work at phone width? |
| Lighthouse | What do the performance and accessibility checks report? |
Whose bug is it?
Request is red or returns 4xx/5xx -> backend
Request is 200, data is right, screen wrong -> frontend
Request never appears -> frontend never asked
Performance
| Metric | Human question | Good | Poor |
|---|---|---|---|
| TTFB | How long before the server said anything? | At most 0.8s | Over 1.8s |
| FCP | When did any content appear? | At most 1.8s | Over 3.0s |
| LCP | When did the main thing appear? | At most 2.5s | Over 4.0s |
| INP | When I tap, does the page respond? | At most 200ms | Over 500ms |
| CLS | Does the page jump around? | At most 0.1 | Over 0.25 |
LCP, INP and CLS are the Core Web Vitals. They are measured at the 75th percentile of real users. FID retired; INP replaced it in March 2024. TBT is a lab stand-in for INP.
Field data comes from real users and real devices. Lab data is a controlled diagnosis. When they disagree, believe the field data.
Three fixes to try first
- Set image width and height, and reserve space for late-loading content to reduce CLS.
- Do not lazy-load the hero image. Serve it as WebP or AVIF to help LCP.
- Keep long work out of click handlers to improve INP.
Images
- Use WebP or AVIF for photos.
- Use
srcsetandsizesso a phone does not download a 3000-pixel image. - Set
widthandheightto reserve space. - Prioritize the hero image; lazy-load content below the fold.
Virtualization and bundles
Virtualization renders only the list items on screen and recycles them as you scroll. A list of 10,000 posts might keep about 10 items in the DOM. TanStack Virtual and react-window do this on the web; RecyclerView and FlatList use the same idea.
- Tree shaking: remove code that is never imported. It works with ES modules.
- Code splitting: load a feature only when it is needed, with
lazy(() => import(...))ornext/dynamic. - Check a package's size before adding it with pkg-size.dev or bundlephobia.com.
Caching
Browser cache and app query cache -> CDN -> server cache -> database
| Resource | Cache-Control | Reason |
|---|---|---|
| Hashed JavaScript file | public, max-age=31536000, immutable | The filename changes with the content. |
| HTML page | no-cache plus short CDN s-maxage | Check for a new deploy. |
| Public API | public, s-maxage=60, stale-while-revalidate=300 | Let the CDN absorb repeat traffic. |
| Personal API | private, no-store | Keep one person's data out of shared caches. |
no-cachemeans keep a copy but check before using it.no-storemeans do not keep it.max-ageapplies to browsers too.s-maxageapplies to shared caches such as a CDN.- In Next.js,
export const revalidate = 60sets an ISR interval.revalidatePathandrevalidateTagclear the Next.js cache, not the CDN. - Cmd+Shift+R clears your browser cache. A stale page can also mean a deploy is unfinished or a CDN still has an old copy.
- HTML, JavaScript, CSS and JSON compress well with gzip or Brotli. Check
content-encoding.
If another user's name appears on your screen, treat it as a P0. A shared cache may be serving personal data.
React in six lines
function DishCard({ dish, onAdd }) {
const [qty, setQty] = useState(0);
const total = qty * dish.price;
useEffect(() => {
const id = setInterval(tick, 1000);
return () => clearInterval(id);
}, []);
return <button onClick={() => onAdd(dish)}>Add: {total}</button>;
}
- Props are the arguments, such as
dishandonAdd. - State is component memory and the signal to redraw.
- Derived values are calculated from state and cannot go stale.
- Effects connect to timers, APIs and analytics. Clean them up.
- Keys should use a stable ID, never an array index.
The PW stack
| Tool | What it is | Example repo |
|---|---|---|
| React | The UI library | Everywhere |
| Next.js | React with a server, routing and SEO tools | pw-talk-web, center-page, pw-live-class-fe |
| Rsbuild and Module Federation | Build and load widgets at runtime | react-batches, help-centre-react-fe |
| Tailwind CSS | Style by composing utility classes | Modern repos |
| TanStack Query | Loading, errors, caching and refetching for API calls | Most repos |
@pw-tech/omni-ui | Shared component library | Most repos |
| pnpm | Package manager. Avoid mixing package managers in one repo. | Most repos |
| Sentry and Grafana Faro | Error and performance monitoring | Most repos |
| CloudFront | CDN in front of pw.live | Check x-cache in DevTools |
Module Federation is like a shaadi buffet: different teams run their own counters, but guests see one party.
Working with AI
Give an AI four things before it writes code:
- Brand: exact colours, font, radius and spacing.
- Structure: the sections, in order.
- Constraints: file count, dependencies and layout approach.
- Quality bar: semantic HTML, image dimensions and alt text, visible focus, responsive layout and no layout shift.
Build a responsive page with semantic HTML and CSS Grid.
Use real buttons, visible :focus-visible states, and meaningful alt text.
Reserve space for images and late-loading content. Keep it usable at phone width.
Ask it to explain the result line by line, then review the output. AI can write a first draft; it cannot decide whether the draft is good.
Five-minute pre-ship check
- Console has no errors.
- Network requests succeed and none take over one second.
- Page works on Slow 4G and 4x CPU throttling.
- No horizontal scroll at phone width.
- Tab through the page and check that focus stays visible.
- Lighthouse accessibility score is above 90.
- Loading, empty and error states are present.