🚀 SurfSense 2026 Roadmap

[MODSetter]

SurfSense Contribution Roadmap

Welcome contributors! This discussion tracks the current set of curated good first issues for the SurfSense frontend (surfsense_web/). All issues are deeply verified before being added here — each one has a clear scope, a safe fix path, and acceptance criteria.

If you'd like to pick one up, drop a comment on the issue and we'll assign it.

---

How to get started

1. Read the project's CONTRIBUTING guide.
2. Browse the categorized list below and pick an issue that matches your interest.
3. Comment on the issue to claim it.
4. Open a PR and link it back to the issue.

---

🏗️ Architecture / Refactor

These improve the codebase's structural health — reducing duplication, fixing leaky module boundaries, and deepening interfaces.

• Extract a shared thread-timestamp formatter for the chats sidebars (currently duplicated) #1376 — Extract a shared thread-timestamp formatter for the chats sidebars (currently duplicated)
• Move getConnectorTelemetryMeta out of components/ so lib/posthog/events.ts doesn't depend upward into UI #1375 — Move getConnectorTelemetryMeta out of components/ so lib/posthog/events.ts doesn't depend upward into UI
• Replace inline process.env.NEXT_PUBLIC_FASTAPI_BACKEND_URL reads with BACKEND_URL from lib/env-config #1374 — Replace inline process.env.NEXT_PUBLIC_FASTAPI_BACKEND_URL reads with BACKEND_URL from lib/env-config
• Use z.infer types from contracts/types/log.types.ts instead of redefining Log/LogFilters/LogSummary in use-logs.ts #1372 — Use z.infer types from contracts/types/log.types.ts instead of redefining Log/LogFilters/LogSummary in use-logs.ts
• Make cacheKeys.*.withQueryParams keys order-stable (sort entries instead of Object.values) #1370 — Make cacheKeys.*.withQueryParams keys order-stable (sort entries instead of Object.values)
• Extract a single extractDomain helper — currently duplicated in 4 places with 3 different fallbacks #1368 — Extract a single extractDomain helper — currently duplicated in 4 places with 3 different fallbacks
• Extract shared hasPermission helper instead of duplicating the predicate in two components #1366 — Extract shared hasPermission helper instead of duplicating the predicate in two components
• Drop redundant localStorage.setItem in TokenHandler (already done by setBearerToken) #1365 — Drop redundant localStorage.setItem in TokenHandler (already done by setBearerToken)
• Centralize surfsense_redirect_path localStorage key behind auth-utils #1364 — Centralize surfsense_redirect_path localStorage key behind auth-utils
• Delete unused notesApiService (orphan API module) #1363 — Delete unused notesApiService (orphan API module)
• Define a typed contract for the OAuth callback cookie in contracts/types/oauth.types.ts #1362 — Define a typed contract for the OAuth callback cookie in contracts/types/oauth.types.ts
• Use updateSearchSpaceMutationAtom in prompt-config-manager instead of raw authenticatedFetch #1361 — Use updateSearchSpaceMutationAtom in prompt-config-manager instead of raw authenticatedFetch
• Shrink LayoutShell.documentsPanel interface: drop unused isDocked / onDockedChange #1360 — Shrink LayoutShell.documentsPanel interface: drop unused isDocked / onDockedChange
• Replace SLIDEOUT_PANEL_OPENED_EVENT window event with a jotai "ticks" atom #1358 — Replace SLIDEOUT_PANEL_OPENED_EVENT window event with a jotai "ticks" atom

🐛 Bug Fixes

Real bugs with clear, low-risk fixes.

• Stop double-toasting on mutation errors: set meta.suppressGlobalErrorToast on mutations with their own onError toast #1371 — Stop double-toasting on mutation errors: set meta.suppressGlobalErrorToast on mutations with their own onError toast
• Fix log mutations: invalidate the keys useLogs actually subscribes to #1369 — Fix log mutations: invalidate the keys useLogs actually subscribes to
• Reset expanded state when chunkId changes in CitationPanelContent #1367 — Reset expanded state when chunkId changes in CitationPanelContent
• Use shared useIsMobile (768px) in SidebarSlideOutPanel instead of an ad-hoc 640px media query #1359 — Use shared useIsMobile (768px) in SidebarSlideOutPanel instead of an ad-hoc 640px media query

⚡ Performance

• Build index Maps for repeated .find() lookups in chat and document hooks #1047 — Build index Maps for repeated .find() lookups in chat and document hooks
• Defer PostHog loading from the critical bundle path #1044 — Defer PostHog loading from the critical bundle path

🎨 UX

• Add error state handling in general settings manager #911 — Add error state handling in general settings manager

📖 Documentation

• Fix PlateEditor JSDoc — actual save shortcut is Mod+Shift+S, not ⌘+S #1373 — Fix PlateEditor JSDoc — actual save shortcut is Mod+Shift+S, not ⌘+S

---

A note on quality

Past rounds of "good first issues" sometimes resulted in subtle bugs because the proposed fixes weren't deeply verified. This batch (and going forward) follows a stricter rule:

• Each issue is manually verified in the actual code before posting.
• The fix is mechanically safe — no risky refactors or speculative redesigns.
• Acceptance criteria spell out exactly what "done" looks like.

If you spot anything off in an issue — missing context, an unsafe assumption, or a behavior you don't think we should change — please call it out on the issue thread before opening a PR.

Happy contributing!