npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@convex-dev/react-query

v0.0.0-alpha.8

Published

Instead of polling you subscribe to receive update from server-side query functions in a Convex deployment. Convex is a database with server-side (db-side? like stored procedures) functions that update reactively.

Downloads

3,830

Readme

@convex-dev/react-query

Instead of polling you subscribe to receive update from server-side query functions in a Convex deployment. Convex is a database with server-side (db-side? like stored procedures) functions that update reactively.

New results for all relevant subscriptions are pushed to the client where they update at the same time so data is never stale and there's no need to call queryClient.invalidateQueries().

Setup

See ./src/example.tsx for a real example. The general pattern:

  1. Create a ConvexClient and ConvexQueryClient. Set the global default queryKeyHashFn to convexQueryClient.hashFn() and queryFn to convexQueryClient.queryFn(). Connect the ConvexQueryClient to the React Query QueryClient.
const convexClient = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);
const convexQueryClient = new ConvexQueryClient(convexClient);
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      queryKeyHashFn: convexQueryClient.hashFn(),
      queryFn: convexQueryClient.queryFn(),
    },
  },
});
convexQueryClient.connect(queryClient);
  1. Use useQuery() with the convexQuery options factory function called with an api object imported from ../convex/_generated/server and the arguments for this query function. These two form the query key.
const { isPending, error, data } = useQuery({
  ...convexQuery(api.repos.get, { repo: "made/up" }),
  gcTime: 10000, // unsubscribe after 10s of no use
});

staleTime is set to Infinity beacuse this data is never stale; it's proactively updated whenever the query result updates on the server. (see tkdodo's post for more about this) If you like, customize the gcTime to the length of time a query subscription should remain active after all useQuery() hooks using it have unmounted.

If you need to use a Convex Action as a query, it won't be reactive; you'll get all the normal tools from React Query to refetch it.

Differences from using TanStack Query with fetch

New query results are pushed from the server, so a staleTime of Infinity should be used.

Your app will remain subscribed to a query until the gcTime has elapsed. Tune this for your app: it's usually a good tradeoff to use a value of at least a couple seconds.

Example

To run this example:

  • npm install
  • npm run dev

Mutations and Actions

If you wrap your app in a ConvexProvider you'll be able to use convex hooks like useConvexMutation and useConvexAction.:

<ConvexProvider client={convex}>
  <QueryClientProvider client={queryClient}>
    <App />
  </QueryClientProvider>
</ConvexProvider>

You can use this mutation function directly or wrap it in a TanStack Query useMutation:

const mutationFn = useConvexMutation(api.board.createColumn);
const { mutate } = useMutation({ mutationFn });
const { mutate } = useMutation({
  mutationFn: useConvexAction(api.time.getTotal),
});

Authentication (example TODO)

TanStack Query isn't opionated about auth; an auth code might be a an element of a query key like any other. With Convex it's not necessary to add an additional key for an auth code; auth is an implicit argument to all Convex queries and these queries will be retried when authentication info changes.

Convex auth is typically done via JWT: some query functions will fail if requested before calling convexReactClinet.setAuth() with a function that provides the token.

Auth setup looks just like it's recommended in Convex docs, which make use of components that use native convex hooks. For Clerk, this might look like this: a ClerkProvider for auth, a ConvexProviderWithClerk for the convex client, and a QueryClient.

<ClerkProvider publishableKey="pk_test_...">
  <ConvexProviderWithClerk client={convex} useAuth={useAuth}>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </ConvexProviderWithClerk>
</ClerkProvider>

See the Convex Auth docs for setup instructions.

TODO

  • auth
  • paginated queries
  • cleanup / unsubscribe in useEffect; something with hot reloading may not be working right

Contributing

After cloning this repo run npm i to install dependencies. This package uses tshy to publish an ESM. If there's ever demand for a CJS build we can add "cjs" to the "dialects" section of "tshy" config in the package.json.

To publish an alpha release, update the version in package.json to something like 0.0.0-alpha.1 and run npm publish --tag alpha.

To publish a regular release, update the version in package.json to something like 0.1.2 and run npm publish.