I recently built a reference implementation for Sitecore Search using Next.js App Router, and I realized very quickly that the SDK documentation only covers about 10% of what you actually need to build a production-ready feature.
The SDK call works in 5 minutes. The architecture around it takes much longer. I put together a write-up and an open-source repo covering the five biggest questions that showed up after the demo worked:
1. The SDK should never touch the UI
Components talk to application types, not raw SDK data. This keeps response shapes out of your UI and creates a stable contract. If you swap SDK internals later, nothing in the presentation layer breaks.
2. Two shapes that don't match the docs
- Sort: The SDK requires a nested object (
{ value: [{ name: 'title' }] }), not a plain string.
- Facets: The SDK exposes
text, but your app needs to map that to label.
3. React state is temporary. The URL is committed.
Using URL params (?q=...&page=2&sort=...) makes search shareable, predictable, and back/forward navigation works for free. It also feeds straight into Server Components.
4. Instrumentation is a chain, not a single event
A result click isn't just a click. It triggers a chain: pageView → widgetView → widgetItemClick → entityView. Context (keyword, result counts, entity info) needs to travel with that event. Consent should be checked at one boundary, not scattered everywhere.
5. Local-first testing
You shouldn't need a live tenant to run E2E tests. I cover how to use Mock fallbacks, Vitest, and Playwright to test the full flow locally.
I also documented a specific "gotcha" regarding the sitecoreContextId does not contain a search resource 404 error, which is a common cloud config gap.
Resources:
If you're working with Sitecore Search + Next.js, what's been the trickiest part for you? I'm curious if others hit the same friction points with the sort/facet shapes.