Refactor FE API v2 interface + current visitors bugfix by RobertJoonas · Pull Request #6351 · plausible/analytics

RobertJoonas · 2026-05-13T20:18:52Z

Changes

For reviewers: commit-by-commit highly recommended

Makes the API interface more solid on the frontend. Smaller improvements should be pretty self-explanatory and easy to understand when skimming through the PR commit by commit.

There were also some bigger API v2 interface design changes though.

1. Introduce `use-query-api.ts`

It's a module containing two hooks:

useQueryApi (new)
- handles realtime refetch logic (returns {apiState, isRealtimeSilentUpdate})
- built-in cache TTL logic (nothing the caller should be concerned about anymore)
- can be used by every report that targets the /query API, except for details views
useSearchAndPaginateQueryApi (partially existing as usePaginatedQueryApi)
- added search functionality, which is why the name change -- if there's a non-empty search string (that's also included in the query key as it affects query uniqueness) a ['contains', dimensions[0], [searchString]] filter gets added to the constructed statsQuery.

Both hooks now operate with a queryKey of a new unified type -- StatsReportQueryKey.

2. The bug fix

To be able to switch to the new hook in top stats, the "current visitors" query had to be extracted somewhere else. We're using current visitors in two places, so it makes sense for them to be fetched in a single context. Doing that, I also discovered a bug in shared links limited to a segment, where realtime top stats fetch current visitors from the /query API, enforcing the segment filter -- 400 returned while should allow current visitors to ignore even the enforced segment filter. This PR fixes that by revertingg back to the old /current-visitors endpoint.

Tests

Tests have been adjusted. More coverage to be added in upcoming PRs

Changelog

This PR does not make a user-facing change

Documentation

This change does not need a documentation update

Dark mode

This PR does not change the UI

… enum

- usePaginatedQueryApi -> useSearchAndPaginateQueryApi (include addSearchFilter logic in the hook) - enforce dimensions on ReportParams type and make it a part of queryKey - define explicit StatsReportQueryKey type

The new hook also includes automatic realtime re-fetch logic.

- fixes a bug: current visitors in realtime top stats, in shared links limited to segment, are fetched from /query api which enforces segment filter -> 400 Bad Request - uses Tanstack useQuery against the old GET endpoint - The value is now also cached for 30s (CACHE_TTL_REALTIME) - Do not fetch current visitors at all when not needed (i.e. not realtime and dashboard has filters applied). - The same context value is now used by both top-stats.js and current-visitors.js

github-actions · 2026-05-13T20:41:22Z

Preview environment👷🏼‍♀️🏗️
PR-6351

apata

I think it's going in a good direction. Maybe the useQuery wrapper could be thinner, but that's just my personal preference. I appreciate the refactor to make greater use of query-api-schema.json!

apata · 2026-05-14T09:07:07Z

-  }, [dashboardState, updateCount])
-
-  if (currentVisitors !== null && dashboardState.filters.length === 0) {
+  if (currentVisitors !== null) {


question, non-blocking: why is the guard against dashboardState.filters.length === 0 not needed any more?

I moved this into the context provider. It now only fetches current visitors if isRealTimeDashboard(dashboardState) || dashboardState.filters.length === 0. If this condition is not met, the query is not executed and CurrentVisitorsContext.Provider provides the value as null. Therefore, the additional filter length check in the CurrentVisitors component is redundant.

Forgot to mention this in the PR description but this is actually a pretty important fix. Currently on production, if there are filters applied and period != realtime, we still fetch current visitors. To see the behaviour on prod, go to https://plausible.io/plausible.io?f=is,page,/:dashboard&period=28d and monitor the network tab until a realtime tick. You can see a redundant GET /current-visitors request even though the value never gets rendered. This PR fixes that.

Thanks for clarifying! Should it be the responsibility of current visitors context to toggle this top bar component on and off? Is data === null the best signal for that?

IMHO completely fine to let the context decide in what situation the value is needed to be fetched. It's not only up to the context to decide whether to render it though. E.g. TopBar also takes a showCurrentVisitors prop which is false on a realtime dashboard. And top stats only renders it in realtime.

apata · 2026-05-14T09:12:00Z

+// Added client-side in the queryFn before storing to TanStack cache.
+// Needed to make sure that the time/metric labels we're constructing
+// in stats reports are in sync with the dashboardState that was used
+// to make that query. Otherwise, relying on current dashboardState
+// while rendering previous (placeholder) data, it'd be out of sync.
+export type ExtraContext = {
+  isRealtime: boolean
+  hasConversionGoalFilter: boolean
+}
+
 export type QueryApiResponse = {
  query: QueryResultQuery
  meta: QueryResultMeta
  results: QueryResultRow[]
+  extraContext: ExtraContext
 }


issue, non-blocking: I think useQuery has API for this so we don't actually need to hand roll it. Check the description for meta at https://tanstack.com/query/latest/docs/framework/react/reference/useQuery. I didn't try it yet locally, but I think we should

I don't think that solves the problem with rendering previousData. As soon as queryKey changes, meta does too. In other words, it will always represent the dashboardState of the current (new) query, rather than placeholderData.

RobertJoonas added 11 commits May 13, 2026 21:27

more specific type to event:props:* dimension

224bbdc

rename use-order-by.ts -> use-metric-order-by.ts

643b53f

SortDirection: use string union type from query-api-schema instead of…

53e0a45

… enum

use query-api-schema pagination type too

5915c9d

add proper OrderBy type (with dimensions) and separate MetricOrderBy

19ecf02

use NonTimeDimension type in v2 breakdown components

7990e9c

also create a Dimension type (incl time dims)

320d00a

create use-query-api.ts

567d615

- usePaginatedQueryApi -> useSearchAndPaginateQueryApi (include addSearchFilter logic in the hook) - enforce dimensions on ReportParams type and make it a part of queryKey - define explicit StatsReportQueryKey type

add a useQueryApi hook and use it in IndexBreakdown

897104a

The new hook also includes automatic realtime re-fetch logic.

top stats and main graph to useQueryApi

2b419a1

RobertJoonas added the preview label May 13, 2026

RobertJoonas mentioned this pull request May 14, 2026

Fix realtime top stats in limited to segment shared link #6341

Closed

4 tasks

RobertJoonas requested a review from apata May 14, 2026 06:33

RobertJoonas added 2 commits May 14, 2026 11:11

DetailsBreakdown: addSearchFilter -> searchEnabled

cd9eb05

Merge remote-tracking branch 'origin/master' into fe-api-v2-refactor

91f2ed9

apata approved these changes May 14, 2026

View reviewed changes

RobertJoonas added 5 commits May 14, 2026 13:22

extractIntervalFromDimensions utility

f395656

create new statsQuery with spread

b0d5034

remove redundant useMemo

47380b4

remove redundant as type casts

a8efa58

move and improve comment

3b02b1f

RobertJoonas added this pull request to the merge queue May 14, 2026

Merged via the queue into master with commit 82c7b0e May 14, 2026
37 of 39 checks passed

RobertJoonas deleted the fe-api-v2-refactor branch May 14, 2026 11:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Refactor FE API v2 interface + current visitors bugfix#6351

Refactor FE API v2 interface + current visitors bugfix#6351
RobertJoonas merged 18 commits into
masterfrom
fe-api-v2-refactor

RobertJoonas commented May 13, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 13, 2026

Uh oh!

apata left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

apata May 14, 2026

Uh oh!

RobertJoonas May 14, 2026

Uh oh!

apata May 14, 2026

Uh oh!

RobertJoonas May 14, 2026 •

edited

Loading

Uh oh!

apata May 14, 2026

Uh oh!

RobertJoonas May 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

RobertJoonas commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

1. Introduce use-query-api.ts

2. The bug fix

Tests

Changelog

Documentation

Dark mode

Uh oh!

github-actions Bot commented May 13, 2026

Uh oh!

apata left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

apata May 14, 2026

Choose a reason for hiding this comment

Uh oh!

RobertJoonas May 14, 2026

Choose a reason for hiding this comment

Uh oh!

apata May 14, 2026

Choose a reason for hiding this comment

Uh oh!

RobertJoonas May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

apata May 14, 2026

Choose a reason for hiding this comment

Uh oh!

RobertJoonas May 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

RobertJoonas commented May 13, 2026 •

edited

Loading

1. Introduce `use-query-api.ts`

RobertJoonas May 14, 2026 •

edited

Loading