fix(react): usePGlite returns null instead of throwing outside provider

packages/pglite-react/src/hooks.ts

@@ -44,6 +44,7 @@ function useLiveQueryImpl<T = { [key: string]: unknown }>(
 
   /* eslint-disable @eslint-react/hooks-extra/no-direct-set-state-in-use-effect */
   useEffect(() => {
+    if (!db) return // no PGliteProvider mounted � skip subscription
     let cancelled = false
     const cb = (results: LiveQueryResults<T>) => {
       if (cancelled) return

packages/pglite-react/src/provider.tsx

@@ -9,7 +9,7 @@ interface Props<T extends PGliteWithLive> {
 type PGliteProvider<T extends PGliteWithLive> = (
   props: Props<T>,
 ) => React.JSX.Element
-type UsePGlite<T extends PGliteWithLive> = (db?: T) => T
+type UsePGlite<T extends PGliteWithLive> = (db?: T) => T | null
 
 interface PGliteProviderSet<T extends PGliteWithLive> {
   PGliteProvider: PGliteProvider<T>
@@ -28,12 +28,9 @@ function makePGliteProvider<T extends PGliteWithLive>(): PGliteProviderSet<T> {
       // allow providing a db explicitly
       if (db !== undefined) return db
 
-      if (!dbProvided)
-        throw new Error(
-          'No PGlite instance found, use PGliteProvider to provide one',
-        )
-
-      return dbProvided
+      // Return null instead of throwing when no provider is mounted.
+      // Callers can guard with `if (!db) return` for lazy / conditional rendering.
+      return dbProvided ?? null
     }) as UsePGlite<T>,
     PGliteProvider: ({ children, db }: Props<T>) => {
       return <ctx.Provider value={db}>{children}</ctx.Provider>

packages/pglite-react/test/provider.test.tsx

@@ -41,3 +41,20 @@ describe('provider', () => {
     await waitFor(() => expect(result.current).toBe(db))
   })
 })
+
+describe('usePGlite outside provider', () => {
+  it('returns null when no PGliteProvider is mounted', () => {
+    const { result } = renderHook(() => usePGlite())
+    expect(result.current).toBeNull()
+  })
+
+  it('does not throw when no PGliteProvider is mounted', () => {
+    expect(() => renderHook(() => usePGlite())).not.toThrow()
+  })
+
+  it('returns the db when provided directly as argument', async () => {
+    const db = await PGlite.create({ extensions: { live } })
+    const { result } = renderHook(() => usePGlite(db as PGliteWithLive))
+    expect(result.current).toBe(db)
+  })
+})