RFC: V3 API design

[boschni]

The bundle size of React Query has been increasing lately as more features are being added.
While the size increase is inevitable, it would be nice to only "pay" for what you use.

In the current V3 API, most functionality is tied together with QueryClient.
This allows for easy discoverability and adds some convenience because everything is in one place.
The downside of this approach is that it cannot be tree-shaked.

This proposal explores how a different API with better tree shaking support would look like.
With the current set of features it reduces the bundle size from 36kB to 24kB (8.58 kB vs 6.67 kB gzipped) when only importing useQuery.

// A query store contains queries (can be omitted when not using queries)
const queryStore = new QueryStore()

// A mutation store contains mutations (can be omitted when not using mutations)
const mutationStore = new MutationStore()

// An environment contains configuration, plugins and connected stores
const environment = new Environment({
  queryStore,
  mutationStore,
  plugins: [],
  defaultOptions: {
    queries: {
      staleTime: Infinity
    },
  }
})

// connect the environment to a component tree
function App {
  return (
   <EnvironmentProvider environment={environment}>
     ...
   </EnvironmentProvider>
  )
}

// Hook query client (will use context environment)
function Component {
  const queryClient = useQueryClient()
  queryClient.refetchQueries()
}

// Hook mutation client (will use context environment)
function Component {
  const mutationClient = useMutationClient()
  mutationClient.mutate()
}

// Imperative query client
const queryClient = new QueryClient({ environment })
queryClient.prefetchQuery('todo', () => 'todo')
queryClient.refetchQueries()

// Imperative mutation client
const mutationClient = new MutationClient({ environment })
mutationClient.mutate('todo', () => 'todo')

// Imperative observe query
const queryObserver = new QueryObserver({
  environment,
  options: {
    queryKey: 'todo',
    queryFn: () => 'todo'
  }
})

// Hydration
const state = dehydrate(environment)
hydrate(environment, state)

// Devtools
function Component {
  <Devtools environment={environment} />
}

// Set defaults for queries matching the `todo` key
environment.setQueryDefaults('todo', { queryFn: () => 'todo' })

// Set defaults for mutations matching the `addTodo` key
environment.setMutationDefaults('addTodo', { mutationFn: text => text })

As some might notice, the design is inspired by https://relay.dev/docs/en/relay-environment.

[tannerlinsley]

Very cool. I can see some of the language here is already a departure from what v3 beta is today, right?

[tannerlinsley]

If you’re up to the task, let’s do it. I’d love to hear the overview on the reorganization.

[tannerlinsley]

I also think this would be a good time to migrate the core to the query package (https://github.com/TanStack/query)

[sundarsu]

I'm curious if this was actioned or might be addressed in v4?

[TkDodo]

no, we don't plan on changing that right now.

[sundarsu]

@TkDodo - I'd started another possibly related thread here: #3435
It doesn't look like tree-shake in v3 works too good unfortunately and this bloats the package size.
Thoughts/comments?