Engineering Lessons

Bite-sized lessons learned while building Pulse. Each card covers a real bug, pattern, or decision — with code examples and the story behind it.

10 lessons across 4 categories

Next.js (3)TypeScript (1)React (5)Architecture (1)

Next.js

(3)

Next.jsIntermediate

Always try-catch optional auth in public pages

When calling getAuthSession() in a server component that serves both authenticated and anonymous users, the auth library may throw if there are no valid cookies — not just return null.

// Bad: crashes for anonymous visitors
const session = await getAuthSession();

// Good: graceful fallback
let isAuthenticated = false;
try {
  const session = await getAuthSession();
  isAuthenticated = !!session?.user?.id;
} catch {
  // Anonymous visitor — no session
}

Wrap optional auth calls in try-catch. A thrown error in a server component crashes the entire page with a 500.

Learned from: Shared note page was returning 500 for all anonymous visitors after adding auth detection.

Next.jsIntermediate

Middleware public routes vs. in-handler auth checks

Adding a route to middleware PUBLIC_ROUTES skips auth entirely. But if the handler already has its own auth check (like getAuthSession()), adding it to public routes means anyone can hit it.

// middleware.ts — only truly public routes go here
const PUBLIC_ROUTES = [
  '/shared',           // public page
  '/api/chat/guest-v04', // guest API (validates share token internally)
  // '/api/chat/transcribe' — NO! requires auth session
];

// transcribe/route.ts — has its own auth check
const session = await getAuthSession();
if (!session?.user?.id) {
  return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
}

Two-layer auth: middleware gates the route, handler validates permissions. Don't put auth-required endpoints in PUBLIC_ROUTES just because a public page calls them.

Learned from: Added transcribe to public routes for guest mic access, but it needs auth for the Whisper API key lookup.

Next.jsIntermediate

Preserve callbackUrl through OAuth sign-in flow

When a user hits a feature requiring auth on a public page, redirect to /auth/signin?callbackUrl=/current-page. The sign-in page reads this param and passes it to the OAuth provider.

// Client-side: redirect to sign-in with callback
if (!isAuthenticated) {
  window.location.href =
    '/auth/signin?callbackUrl=' +
    encodeURIComponent('/shared/' + token);
  return;
}

The middleware already sets callbackUrl when redirecting protected routes. For optional auth features, manually construct the redirect URL with the current path.

Learned from: Guest users clicking mic on shared page need to sign in and return to the same shared note.

TypeScript

(1)

TypeScriptBeginner

Whitelist HTML tags in content format detection

A naive regex like /<\/?[a-z][\s\S]*>/i to detect HTML will match markdown content containing angle brackets like <Agent>, <5 minutes>, or <UserName>.

// Bad: false positives on markdown
const htmlRegex = /<\/?[a-z][\s\S]*>/i;

// Good: only match real HTML elements
const htmlRegex = /<\/?(?:div|span|p|br|h[1-6]|ul|ol|li|table|...)\b[^>]*\/?>/i;

Use a whitelist of known HTML element names (div, span, p, h1, etc.) instead of matching any angle-bracket pattern.

Learned from: Markdown notes containing "<Agent>" were being classified as HTML and rendered incorrectly.

React

(5)

ReactBeginner

Mobile tab switcher with CSS-only show/hide

When a page has two panels side-by-side on desktop, don't just stack them on mobile — they'll both fight for space. Use a tab switcher that toggles visibility via CSS classes.

// Both panels always mounted, CSS controls visibility
<aside className={`${activeTab !== 'chat' ? 'hidden lg:block' : ''}`}>
  <Chat />  {/* State preserved even when hidden */}
</aside>
<section className={`${activeTab !== 'note' ? 'hidden lg:block' : ''}`}>
  <Content />
</section>

Keep both panels mounted (preserves state like chat history) but use hidden/block toggle. Use lg:block to force both visible on desktop.

Learned from: Shared note page was unusable on mobile — both chat and note panels overlapped.

ReactBeginner

Use items-stretch for equal-height grid columns

CSS Grid's default align-items is stretch, but if you override it with items-start, columns won't match heights. Two card panels will look misaligned.

// Misaligned: cards have different heights
<div className="grid grid-cols-2 items-start">

// Aligned: both cards stretch to match
<div className="grid grid-cols-2 items-stretch">

Use items-stretch (Tailwind: items-stretch) when you want grid children to fill equal heights. Combine with h-full and min-h-0 for proper flex behavior.

Learned from: Share page had chat panel shorter than content panel due to items-start.

ReactBeginner

Tame Tailwind prose line-height with prose-sm

Tailwind's prose class uses ~1.75 line-height by default, which makes long articles feel stretched vertically. prose-sm brings it to 1.625 and smaller font size.

// Default prose: 16px / 1.75 line-height (spacious)
<div className="prose">

// Tighter: 14px / 1.5 line-height
<div className="prose prose-sm prose-p:leading-normal
  prose-headings:leading-snug prose-p:my-2">

Layer overrides: prose-sm for base, then prose-p:leading-normal (1.5) and prose-headings:leading-snug (1.375) for tighter control.

Learned from: Shared note content felt too stretched — paragraphs had excessive vertical spacing.

ReactIntermediate

useCallback deps: add every variable referenced in the closure

When you add a new variable to a fetch body inside a useCallback, you must also add it to the dependency array. Otherwise the callback captures the stale initial value.

// Bug: visitorName is always the initial value
const sendMessage = useCallback(async () => {
  fetch('/api', { body: JSON.stringify({ visitorName }) });
}, [token, sessionKey]); // missing visitorName!

// Fix: include visitorName in deps
}, [token, sessionKey, visitorName]);

After editing a useCallback body, always scan for new variables and update the deps array. React's exhaustive-deps lint rule catches this.

Learned from: Added visitorName to guest chat POST body but forgot to update the useCallback dependency array.

ReactBeginner

Use opacity modifiers for subtle borders

Tailwind's border-gray-200 can feel heavy. Adding an opacity modifier like border-gray-200/70 softens the border while maintaining the color.

// Heavy border
<div className="border border-gray-200">

// Softer, 70% opacity
<div className="border border-gray-200/70
  dark:border-gray-800/70">

Opacity modifiers work on any Tailwind color utility: bg-white/50, text-gray-900/80, border-blue-300/60. Great for matching light/dark themes.

Learned from: Share page cards had visually heavy borders that dominated the layout.

Architecture

(1)

ArchitectureIntermediate

Inject visitor identity into AI system prompts

When an authenticated user interacts with a shared AI agent, passing their name to the system prompt lets the AI personalize responses — "Hi Alex, here's what this note covers...".

// API route: prefer session over client-sent name
const visitorName = typeof body.visitorName === 'string'
  ? body.visitorName.trim().slice(0, 100)
  : undefined;

// System prompt injection
...(visitorName
  ? [`The visitor's name is "${visitorName}".`]
  : []),

Trust server-side session data over client-sent names. Sanitize and limit length (e.g., .slice(0, 100)) to prevent prompt injection.

Learned from: Shared note AI agent had no idea who it was talking to — felt impersonal.

New lessons are added as we encounter interesting patterns, bugs, and solutions.

Back to Docs

// Bad: crashes for anonymous visitors const session = await getAuthSession(); // Good: graceful fallback let isAuthenticated = false; try { const session = await getAuthSession(); isAuthenticated = !!session?.user?.id; } catch { // Anonymous visitor — no session }

// middleware.ts — only truly public routes go here const PUBLIC_ROUTES = [ '/shared', // public page '/api/chat/guest-v04', // guest API (validates share token internally) // '/api/chat/transcribe' — NO! requires auth session ]; // transcribe/route.ts — has its own auth check const session = await getAuthSession(); if (!session?.user?.id) { return NextResponse.json({ error: 'Unauthorized' }, { status: 401 }); }

// Both panels always mounted, CSS controls visibility <aside className={`${activeTab !== 'chat' ? 'hidden lg:block' : ''}`}> <Chat /> {/* State preserved even when hidden */} </aside> <section className={`${activeTab !== 'note' ? 'hidden lg:block' : ''}`}> <Content /> </section>

// Default prose: 16px / 1.75 line-height (spacious) <div className="prose"> // Tighter: 14px / 1.5 line-height <div className="prose prose-sm prose-p:leading-normal prose-headings:leading-snug prose-p:my-2">

// Bug: visitorName is always the initial value const sendMessage = useCallback(async () => { fetch('/api', { body: JSON.stringify({ visitorName }) }); }, [token, sessionKey]); // missing visitorName! // Fix: include visitorName in deps }, [token, sessionKey, visitorName]);

// API route: prefer session over client-sent name const visitorName = typeof body.visitorName === 'string' ? body.visitorName.trim().slice(0, 100) : undefined; // System prompt injection ...(visitorName ? [`The visitor's name is "${visitorName}".`] : []),