@jetblack/duckdb-react

A DuckDB context provider for React.

You can find an example app using vite here, and an example using webpack here.

Development

If you are interested in the implementation, the library code is in lib, and an example application is in src. To use from source, clone the project, install the packages, then run the example with npm run dev.

Installation

Install from npmjs.

1npm install @jetblack/duckdb-react

Usage

Use the DuckDB context provider to connect to the database and provide a context.

Children of the DuckDB component will have access to the database context.

1import DuckDB, { useDuckDB } from '@jetblack/duckdb-react'
2
3import bundles from './bundles'
4
5export default function App() {
6  const useBundles = true
7  const optionalBundles = useBundles ? bundles : undefined
8
9  return (
10    <DuckDB bundles={optionalBundles}>
11      <HelloWorld />
12    </DuckDB>
13  )
14}
15
16function HelloWorld() {
17  // Get the DuckDB context from the hook.
18  const { db, loading, error } = useDuckDB()
19
20  useEffect(() => {
21    if (loading || !db || error) {
22      return
23    }
24
25    // Do something with duckdb.
26
27  }, [loading, db, error])
28
29  return <div>Hello, World!</div>
30}
31

The DuckDB component takes the following properties:

• bundles: DuckDBBundles | undefined - see the section on bundles below,
• config: DuckDBConfig | undefined - Optional configuration to apply to the database.
• logger: Logger | undefined - defaults to the built in ConsoleLogger.
• progress: InstantiationProgress | undefined - This is updated during the database instantiation.

The properties returned by useDuckDB are:

• db: AsyncDuckDB | undefined
• loading: boolean
• error: string | Error | undefined

The loading property is initially true, becoming false when either the db property is set, or the error property is set.

Bundles

In order to create the context a wasm "bundle" may be provided. If a bundle is not specified it will be downloaded from the JsDelivr CDN.

If specified the bundle is specific to the development environment. The following gives the bundles defined by the DuckDB documentation.

No bundle

If no bundle is provided the bundle will be discovered from the JsDelivr CDN.

vite

For vite, create the following bundle.ts.

1import { DuckDBBundles } from '@duckdb/duckdb-wasm'
2import duckdbMvpWasm from '@duckdb/duckdb-wasm/dist/duckdb-mvp.wasm?url'
3import duckdbMvpWorker from '@duckdb/duckdb-wasm/dist/duckdb-browser-mvp.worker.js?url'
4import duckdbEHWasm from '@duckdb/duckdb-wasm/dist/duckdb-eh.wasm?url'
5import duckdbEHWorker from '@duckdb/duckdb-wasm/dist/duckdb-browser-eh.worker.js?url'
6
7const VITE_BUNDLES: DuckDBBundles = {
8  mvp: {
9    mainModule: duckdbMvpWasm,
10    mainWorker: duckdbMvpWorker
11  },
12  eh: {
13    mainModule: duckdbEHWasm,
14    mainWorker: duckdbEHWorker
15  }
16}
17
18export default VITE_BUNDLES

webpack

For webpack, create the following bundle.ts.

1import { DuckDBBundles } from '@duckdb/duckdb-wasm'
2import duckdbMvpWasm from '@duckdb/duckdb-wasm/dist/duckdb-mvp.wasm'
3import duckdbEHWasm from '@duckdb/duckdb-wasm/dist/duckdb-eh.wasm'
4
5const WEBPACK_BUNDLES: DuckDBBundles = {
6  mvp: {
7    mainModule: duckdbMvpWasm,
8    mainWorker: new URL('@duckdb/duckdb-wasm/dist/duckdb-browser-mvp.worker.js', import.meta.url).toString(),
9  },
10  eh: {
11    mainModule: duckdbEHWasm,
12    mainWorker: new URL('@duckdb/duckdb-wasm/dist/duckdb-browser-eh.worker.js', import.meta.url).toString(),
13  }
14}
15
16export default WEBPACK_BUNDLES