convex-jotai 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright 2026 Grzegorz Dunin-Ślęczek (https://github.com/grzesiekgs)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# convex-jotai
+
+A lightweight bridge between [Convex](https://www.convex.dev/) and [Jotai](https://jotai.org/) that lets you manage Convex queries, mutations, and actions through Jotai atoms.
+In concept it's similar to [`jotai-tanstack-query`](https://github.com/jotaijs/jotai-tanstack-query), meaning that it allows to access and modify `convex` state within `jotai` atoms.
+Effectively it's drop in replacement for `convex/react`.
+
+# Installation
+
+```bash
+# or any bundler of your choice
+bun add convex jotai convex-jotai
+```
+
+## Peer Dependencies
+
+| Package | Version |
+|---------|---------|
+| `convex` | `>=1.31` |
+| `jotai` | `>=2.6` |
+
+These versions can be downgraded. I've selected latest version as of 06.01.2025. Create a GitHub issue if you would like to change this.
+
+# Quick Start
+
+## Set up the Convex client in your Jotai store
+
+```typescript
+import { ConvexClient } from 'convex/browser';
+import { createStore, Provider } from 'jotai';
+import { convexClientAtom } from 'convex-jotai';
+
+// Create the Convex client.
+// Note that ConvexReactClient is wrapper around ConvexClient.
+// It could be possible to use both convex/react and convex-jotai, but currently that would require ConvexReactClient to expose ConvexClient.
+const convex = new ConvexClient(import.meta.env.VITE_CONVEX_URL);
+// convexClientAtom has to be set before using any of convex atoms. It doesn't necessarily has to be set in module scope.
+// Therefore it's possible to rely on default store provided by jotai Provider.
+const store = createStore();
+store.set(convexClientAtom, convex);
+
+// Wrap your app with the Jotai Provider
+const App: FC = () => {
+  return (
+    <Provider store={store}>
+      <YourApp />
+    </Provider>
+  );
+}
+```
+
+## Define your atoms
+
+```typescript
+import { convexQueryAtom, convexMutationAtom, convexActionAtom } from 'convex-jotai';
+import { api } from '../convex/_generated/api';
+
+const themeQueryAtom = convexQueryAtom(api.settings.get, () => ({ key: 'theme' }));
+const settingsMutationAtom = convexMutationAtom(api.settings.set);
+const eventActionAtom = convexActionAtom(api.actions.event);
+```
+
+## Use atoms in your other atoms or components
+
+```typescript
+import { atom, useAtomValue, useSetAtom } from 'jotai';
+
+const backgroundColorAtom = atom((get) => {
+  const theme = get(themeQueryAtom);
+  // api.settings.get is still loading.
+  if (!theme) {
+    return '#FF0000';
+  }
+
+  if (theme === 'light') {
+    return '#FFFFFF';
+  }
+
+  return '#000000';
+})
+
+const Settings: FC = () => {
+  const backgroundColor = useAtomValue(backgroundColorAtom);
+  const settingsMutation = useSetAtom(settingsMutationAtom);
+  const runEventAction = useSetAtom(eventActionAtom);
+
+  useEffect(() => {
+    runEventAction({ event: 'settings-viewed' });
+  }, [runEventAction])
+
+  return (
+    <div style={{ backgroundColor }}>
+      <button onClick={() => settingsMutation({ key: 'theme', value: 'dark' })}>
+        Set Dark Theme
+      </button>
+      <button onClick={() => settingsMutation({ key: 'theme', value: 'light' })}>
+        Set Light Theme
+      </button>
+    </div>
+  );
+}
+```
+# Deep dive
+More details about the implementation.
+
+## More features
+Find out what else `convex-jotai` can do.
+
+### Dynamic query arguments
+```tsx
+const dynamicSettingsQueryAtom = convexQueryAtom(api.settings.get, (get) => {
+  const userSelectedKey = get(userSelectedKeyAtom);
+
+  return { key: userSelectedKey }
+});
+```
+
+### Support for suspense
+```tsx
+const themeQueryPromiseAtom = convexQueryPromiseAtom(api.settings.get, () => ({ key: 'theme' }));
+```
+
+### Descriptive query result
+```tsx
+const themeQueryResultAtom = convexQueryResultAtom(api.settings.get, () => ({ key: 'theme' }));
+
+const themeQueryResult = useAtomValue(themeQueryResultAtom);
+
+if (themeQueryResult.status === 'loading') {
+  ...
+}
+
+if (themeQueryResult.status === 'success') {
+  themeQueryResult.data
+  ...
+}
+
+if (themeQueryResult.status === 'error') {
+  themeQueryResult.error
+  ...
+}
+```
+
+## `convex/react` vs `convex-jotai`
+
+### Provider Setup
+```tsx
+// convex/react
+import { ConvexProvider, ConvexReactClient } from 'convex/react';
+
+const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);
+
+const App: FC = () => {
+  return (
+    <ConvexProvider client={convex}>
+      <YourApp />
+    </ConvexProvider>
+  );
+}
+
+// convex/jotai
+import { ConvexClient } from 'convex/browser';
+import { createStore, Provider } from 'jotai';
+import { convexClientAtom } from 'convex-jotai';
+
+const convex = new ConvexClient(import.meta.env.VITE_CONVEX_URL);
+const store = createStore();
+store.set(convexClientAtom, convex);
+
+const App: FC = () => {
+  return (
+    <Provider store={store}>
+      <YourApp />
+    </Provider>
+  );
+}
+```
+
+
+### Queries, mutations and actions
+
+```tsx
+// convex/react
+import { useQuery, useMutation, useAction } from 'convex/react';
+import { api } from '../convex/_generated/api';
+
+const theme = useQuery(api.settings.get, { key: 'theme' });
+const settingsMutation = useMutation(api.settings.set);
+const runEventAction = useAction(api.actions.event);
+
+// convex-jotai
+import { convexQueryAtom } from 'convex-jotai';
+import { useAtomValue, useSetAtom } from 'jotai';
+import { api } from '../convex/_generated/api';
+
+const themeQueryAtom = convexQueryAtom(api.settings.get, () => ({ key: 'theme' }));
+const settingsMutationAtom = convexMutationAtom(api.settings.set);
+const eventActionAtom = convexActionAtom(api.actions.event);
+
+const theme = useAtomValue(themeQueryAtom);
+const settingsMutation = useSetAtom(settingsMutationAtom);
+const runEventAction = useSetAtom(eventActionAtom);
+```
+
+# Example
+
+See the [playground app](../../apps/playground/README.md) for a complete working example comparing `convex/react` and `convex-jotai` side-by-side.
+
+# License
+
+[MIT](./LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,45 @@
+import * as jotai0 from "jotai";
+import { Atom, Getter, WritableAtom } from "jotai";
+import { FunctionArgs, FunctionReference, FunctionReturnType } from "convex/server";
+import { ConvexClient, OptimisticUpdate } from "convex/browser";
+
+//#region src/types.d.ts
+type ConvexQueryOptionsGetter<Query extends FunctionReference<'query'>> = (get: Getter) => FunctionArgs<Query>;
+type ConvexQueryErrorResult = {
+  status: 'error';
+  data?: never;
+  error: Error;
+};
+type ConvexQueryLoadingResult = {
+  status: 'loading';
+  data?: never;
+  error?: never;
+};
+type ConvexQuerySuccessResult<T> = {
+  status: 'success';
+  data: T;
+  error?: never;
+};
+type ConvexQueryResult<T> = ConvexQueryErrorResult | ConvexQueryLoadingResult | ConvexQuerySuccessResult<T>;
+//#endregion
+//#region src/atoms/convexQueryResultAtom.d.ts
+declare function convexQueryResultAtom<Query extends FunctionReference<'query'>>(query: Query, queryOptionsGetter: ConvexQueryOptionsGetter<Query>): Atom<ConvexQueryResult<FunctionReturnType<Query>>>;
+//#endregion
+//#region src/atoms/convexClientAtom.d.ts
+declare const convexClientAtom: jotai0.PrimitiveAtom<ConvexClient | null> & {
+  init: ConvexClient | null;
+};
+//#endregion
+//#region src/atoms/convexQueryPromiseAtom.d.ts
+declare function convexQueryPromiseAtom<Query extends FunctionReference<'query'>>(query: Query, queryOptionsGetter: ConvexQueryOptionsGetter<Query>): Atom<Promise<FunctionReturnType<Query>>>;
+//#endregion
+//#region src/atoms/convexQueryAtom.d.ts
+declare function convexQueryAtom<Query extends FunctionReference<'query'>>(query: Query, queryOptionsGetter: ConvexQueryOptionsGetter<Query>): Atom<FunctionReturnType<Query>>;
+//#endregion
+//#region src/atoms/convexMutationAtom.d.ts
+declare function convexMutationAtom<Mutation extends FunctionReference<'mutation'>>(mutation: Mutation, optimisticUpdate?: OptimisticUpdate<FunctionArgs<Mutation>>): WritableAtom<null, [FunctionArgs<Mutation>], FunctionReturnType<Mutation>>;
+//#endregion
+//#region src/atoms/convexActionAtom.d.ts
+declare function convexActionAtom<Action extends FunctionReference<'action'>>(action: Action): WritableAtom<null, [FunctionArgs<Action>], FunctionReturnType<Action>>;
+//#endregion
+export { ConvexQueryErrorResult, ConvexQueryLoadingResult, ConvexQueryOptionsGetter, ConvexQueryResult, ConvexQuerySuccessResult, convexActionAtom, convexClientAtom, convexMutationAtom, convexQueryAtom, convexQueryPromiseAtom, convexQueryResultAtom };

package/dist/index.mjs

@@ -0,0 +1,108 @@
+import { atom } from "jotai";
+import { getFunctionName } from "convex/server";
+import { selectAtom } from "jotai/utils";
+
+//#region src/utils/getLocalConvexQueryResult.ts
+function getLocalConvexQueryResult(convexClient, funcRef, queryOptions) {
+	try {
+		const result = convexClient.client.localQueryResult(getFunctionName(funcRef), queryOptions);
+		if (result === void 0) return { status: "loading" };
+		return {
+			status: "success",
+			data: result,
+			error: void 0
+		};
+	} catch (possiblyError) {
+		return {
+			status: "error",
+			error: possiblyError instanceof Error ? possiblyError : new Error(String(possiblyError))
+		};
+	}
+}
+
+//#endregion
+//#region src/utils/assertConvexClient.ts
+const assertConvexClient = (client) => {
+	if (typeof window === "undefined") throw new Error("convex-jotai: SSR is currently not supported.");
+	if (client === null) throw new Error("convex-jotai: convexClientAtom is not set. Follow the setup guide in the README.");
+	return client;
+};
+
+//#endregion
+//#region src/atoms/convexClientAtom.ts
+const convexClientAtom = atom(null);
+
+//#endregion
+//#region src/atoms/convexQueryResultAtom.ts
+function convexQueryResultAtom(query, queryOptionsGetter) {
+	const queryOptionsAtom = atom((get) => queryOptionsGetter(get));
+	const querySubscriptionAtom = atom((get) => {
+		const convexClient = assertConvexClient(get(convexClientAtom));
+		const queryOptions = get(queryOptionsAtom);
+		const queryResultAtom = atom(getLocalConvexQueryResult(convexClient, query, queryOptions));
+		queryResultAtom.onMount = (setValue) => {
+			return convexClient.onUpdate(query, queryOptions, (update) => setValue({
+				status: "success",
+				data: update
+			}), (error) => setValue({
+				status: "error",
+				error
+			}));
+		};
+		return queryResultAtom;
+	});
+	return atom((get) => {
+		return get(get(querySubscriptionAtom));
+	});
+}
+
+//#endregion
+//#region src/atoms/convexQueryPromiseAtom.ts
+function convexQueryPromiseAtom(query, queryOptionsGetter) {
+	const queryPromiseStateAtom = selectAtom(convexQueryResultAtom(query, queryOptionsGetter), (queryResult, prevState) => {
+		const state = prevState ?? {
+			promiseWithResolvers: Promise.withResolvers(),
+			resolved: false
+		};
+		if (queryResult.status === "loading") {
+			if (!state.resolved) return state;
+			return {
+				promiseWithResolvers: Promise.withResolvers(),
+				resolved: false
+			};
+		}
+		return {
+			promiseWithResolvers: state.promiseWithResolvers,
+			resolved: true
+		};
+	});
+	return atom((get) => get(queryPromiseStateAtom).promiseWithResolvers.promise);
+}
+
+//#endregion
+//#region src/atoms/convexQueryAtom.ts
+function convexQueryAtom(query, queryOptionsGetter) {
+	const queryResultAtom = convexQueryResultAtom(query, queryOptionsGetter);
+	return atom((get) => {
+		return get(queryResultAtom).data;
+	});
+}
+
+//#endregion
+//#region src/atoms/convexMutationAtom.ts
+function convexMutationAtom(mutation, optimisticUpdate) {
+	return atom(null, (get, _set, args) => {
+		return assertConvexClient(get(convexClientAtom)).mutation(mutation, args, { optimisticUpdate });
+	});
+}
+
+//#endregion
+//#region src/atoms/convexActionAtom.ts
+function convexActionAtom(action) {
+	return atom(null, (get, _set, args) => {
+		return assertConvexClient(get(convexClientAtom)).action(action, args);
+	});
+}
+
+//#endregion
+export { convexActionAtom, convexClientAtom, convexMutationAtom, convexQueryAtom, convexQueryPromiseAtom, convexQueryResultAtom };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "convex-jotai",
+  "version": "0.1.0-alpha.0",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "description": "Jotai atoms for Convex queries, mutations, and actions",
+  "keywords": [
+    "jotai",
+    "convex",
+    "react",
+    "state-management",
+    "realtime"
+  ],
+  "author": "Grzegorz Dunin-Ślęczek <grzesiekgs@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/grzesiekgs/jotai-convex.git",
+    "directory": "packages/convex-jotai"
+  },
+  "homepage": "https://github.com/grzesiekgs/jotai-convex#readme",
+  "bugs": {
+    "url": "https://github.com/grzesiekgs/jotai-convex/issues"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "tsc": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "convex": ">=1.31",
+    "jotai": ">=2.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsdown": "0.18.4",
+    "typescript": "5.9.3"
+  }
+}