feat: first iteration on @aave/react package

Author: cesarenaldi

package.json

@@ -19,6 +19,7 @@
     "lint:fix": "biome check --write",
     "new:package": "NODE_OPTIONS='--import tsx' plop --plopfile=plopfile.ts",
     "prepublish": "pnpm run build",
+    "test:react": "vitest --project react",
     "test": "vitest --passWithNoTests"
   },
   "license": "MIT",

packages/react/README.md

@@ -0,0 +1,7 @@
+# `@aave/react`
+
+The official React bindings for the Aave Protocol.
+
+---
+
+

packages/react/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@aave/react",
+  "version": "0.0.0",
+  "description": "The official React bindings for the Aave Protocol",
+  "repository": {
+    "directory": "packages/react",
+    "type": "git",
+    "url": "git://github.com/aave/aave-sdk.git"
+  },
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "import": [
+        "./dist/index.d.ts"
+      ],
+      "require": [
+        "./dist/index.d.cts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup"
+  },
+  "dependencies": {
+    "@aave/client": "workspace:*",
+    "@aave/env": "workspace:*",
+    "@aave/graphql": "workspace:*",
+    "@aave/types": "workspace:*",
+    "urql": "^4.2.2"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.1.8",
+    "ethers": "^6.14.4",
+    "happy-dom": "^18.0.1",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "viem": "^2.31.6",
+    "zksync-ethers": "^6.18.0"
+  },
+  "peerDependencies": {
+    "@types/react": "^19.1.8",
+    "ethers": "^6.14.4",
+    "react": "^19.1.0",
+    "viem": "^2.31.6",
+    "zksync-ethers": "^6.18.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    },
+    "ethers": {
+      "optional": true
+    },
+    "viem": {
+      "optional": true
+    },
+    "zksync-ethers": {
+      "optional": true
+    }
+  },
+  "license": "MIT"
+}

packages/react/src/AaveProvider.tsx

@@ -0,0 +1,42 @@
+import type { AaveClient } from '@aave/client';
+// biome-ignore lint/correctness/noUnusedImports: intentional
+import React, { type ReactNode } from 'react';
+
+import { AaveContextProvider } from './context';
+
+/**
+ * <AaveProvider> props
+ */
+export type AaveProviderProps = {
+  /**
+   * The children to render
+   */
+  children: ReactNode;
+  /**
+   * The Aave client instance to use
+   */
+  client: AaveClient;
+};
+
+/**
+ * Manages the internal state of the Aave SDK.
+ *
+ * ```tsx
+ * import { AaveProvider, AaveClient, mainnet } from '@aave/react';
+ *
+ * const client = AaveClient.create({
+ *   environment: mainnet,
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <AaveProvider client={client}>
+ *        // ...
+ *     </AaveProvider>
+ *   );
+ * }
+ * ```
+ */
+export function AaveProvider({ children, client }: AaveProviderProps) {
+  return <AaveContextProvider client={client}>{children}</AaveContextProvider>;
+}

packages/react/src/context.tsx

@@ -0,0 +1,42 @@
+import type { AaveClient } from '@aave/client';
+import { invariant } from '@aave/types';
+import React, { type ReactNode, useContext } from 'react';
+import { Provider as UrqlProvider } from 'urql';
+
+const AaveContext = React.createContext<AaveClient | null>(null);
+
+/**
+ * @internal
+ */
+export type AaveContextProviderProps = {
+  children: ReactNode;
+  client: AaveClient;
+};
+
+/**
+ * @internal
+ */
+export function AaveContextProvider({
+  children,
+  client,
+}: AaveContextProviderProps) {
+  return (
+    <AaveContext.Provider value={client}>
+      <UrqlProvider value={client.urql}>{children}</UrqlProvider>
+    </AaveContext.Provider>
+  );
+}
+
+/**
+ * Retrieve the injected {@link AaveClient} from the context.
+ */
+export function useAaveClient(): AaveClient {
+  const client = useContext(AaveContext);
+
+  invariant(
+    client,
+    'Could not find Aave SDK context, ensure your code is wrapped in a <AaveProvider>',
+  );
+
+  return client;
+}

packages/react/src/helpers/index.ts

@@ -0,0 +1,3 @@
+export * from './reads';
+export * from './results';
+export * from './tasks';

packages/react/src/helpers/reads.ts

@@ -0,0 +1,47 @@
+import type { AnyVariables, StandardData } from '@aave/graphql';
+import { invariant } from '@aave/types';
+import { useMemo } from 'react';
+import { type TypedDocumentNode, useQuery } from 'urql';
+import { ReadResult, type SuspendableResult } from './results';
+
+/**
+ * @internal
+ */
+export type Suspendable = { suspense: true };
+
+/**
+ * @internal
+ */
+export type UseSuspendableQueryArgs<Value, Variables extends AnyVariables> = {
+  document: TypedDocumentNode<StandardData<Value>, Variables>;
+  variables: Variables;
+  suspense: boolean;
+};
+
+/**
+ * @internal
+ */
+export function useSuspendableQuery<Value, Variables extends AnyVariables>({
+  document,
+  variables,
+  suspense,
+}: UseSuspendableQueryArgs<Value, Variables>): SuspendableResult<Value> {
+  const [{ data, fetching, error }] = useQuery({
+    query: document,
+    variables,
+    context: useMemo(() => ({ suspense }), [suspense]),
+  });
+
+  if (fetching) {
+    return ReadResult.Initial();
+  }
+
+  if (error) {
+    // biome-ignore lint/suspicious/noExplicitAny: temporary workaround
+    return ReadResult.Failure(error) as any;
+  }
+
+  invariant(data, 'No data returned');
+
+  return ReadResult.Success(data.value);
+}

packages/react/src/helpers/results.ts

@@ -0,0 +1,51 @@
+/**
+ * A read hook result.
+ *
+ * It's a discriminated union of the possible results of a read operation:
+ * - Rely on the `loading` value to determine if the `data` or `error` can be evaluated.
+ * - If `error` is `undefined`, then `data` value will be available.
+ */
+export type ReadResult<T, E = never> =
+  | {
+      data: undefined;
+      error: undefined;
+      loading: true;
+    }
+  | {
+      data: T;
+      error: undefined;
+      loading: false;
+    }
+  | {
+      data: undefined;
+      error: E;
+      loading: false;
+    };
+
+/**
+ * @internal
+ */
+export const ReadResult = {
+  Initial: <T, E = never>(): ReadResult<T, E> => ({
+    data: undefined,
+    error: undefined,
+    loading: true,
+  }),
+  Success: <T, E = never>(data: T): ReadResult<T, E> => ({
+    data,
+    error: undefined,
+    loading: false,
+  }),
+  Failure: <T, E = never>(error: E): ReadResult<T, E> => ({
+    data: undefined,
+    error,
+    loading: false,
+  }),
+};
+
+/**
+ * A read hook result that supports React Suspense
+ */
+export type SuspenseResult<T> = { data: T };
+
+export type SuspendableResult<T> = ReadResult<T> | SuspenseResult<T>;