Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rob-blackbourn/jetblack-duckdb-react
Utilities for using DuckDB in react
https://github.com/rob-blackbourn/jetblack-duckdb-react
duckdb duckdb-wasm react
Last synced: about 1 month ago
JSON representation
Utilities for using DuckDB in react
- Host: GitHub
- URL: https://github.com/rob-blackbourn/jetblack-duckdb-react
- Owner: rob-blackbourn
- Created: 2024-02-10T10:22:05.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2024-03-09T07:35:01.000Z (8 months ago)
- Last Synced: 2024-10-03T07:18:45.299Z (about 1 month ago)
- Topics: duckdb, duckdb-wasm, react
- Language: TypeScript
- Homepage:
- Size: 85.9 KB
- Stars: 8
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# @jetblack/duckdb-react
A DuckDB context provider for React.
You can find an example app using vite [here](https://github.com/rob-blackbourn/demo-duckdb-react-vite),
webpack [here](https://github.com/rob-blackbourn/demo-duckdb-react-webpack).
and create-react-app [here](https://github.com/rob-blackbourn/demo-duckdb-react-cra)
## Development
If you are interested in the implementation, the library code is in [`lib`](./lib),
and an example application is in [`src`](./src). To use from source, clone the
project, install the packages, then run the example with `npm run dev`.
## Installation
Install from [npmjs](https://www.npmjs.com/package/@jetblack/duckdb-react).
```bash
npm install @jetblack/duckdb-react
```
## Usage
Use the `DuckDB` context provider to connect to the database.
Children of the `DuckDB` component will have access to the database context.
```typescript
import DuckDB, { useDuckDB } from '@jetblack/duckdb-react'
export default function App() {
return (
)
}
function HelloWorld() {
// Get the DuckDB context from the hook.
const { db, loading, error } = useDuckDB()
useEffect(() => {
if (loading || !db || error) {
return
}
// Do something with duckdb.
}, [loading, db, error])
return
Hello, World!
}
```
The `DuckDB` component takes the following properties:
* `bundles`: [`DuckDBBundles`](https://shell.duckdb.org/docs/interfaces/index.DuckDBBundles.html) `|` `undefined` - see the section on bundles below,
* `config`: [`DuckDBConfig`](https://shell.duckdb.org/docs/interfaces/index.DuckDBConfig.html) `|` `undefined` - Optional configuration to apply to the database.
* `logger`: [`Logger`](https://shell.duckdb.org/docs/interfaces/index.Logger.html) `|` `undefined` - defaults to the built in [`ConsoleLogger`](https://shell.duckdb.org/docs/classes/index.ConsoleLogger.html).
The properties returned by `useDuckDB` are:
* `db`: [`AsyncDuckDB`](https://shell.duckdb.org/docs/classes/index.AsyncDuckDB.html) `|` `undefined` - Set to the database when successfully instantiated.
* `progress`: [`InstantiationProgress`](https://shell.duckdb.org/docs/interfaces/index.InstantiationProgress.html) `|` `undefined` - This is updated during the database instantiation.
* `loading`: `boolean` - This is initially `false`, becoming `true` when either the `db` or `error` property is set.
* `error`: `string | Error | undefined` - Set to the error when instantiation has failed.
### 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](https://duckdb.org/docs/api/wasm/instantiation).
#### No bundle
If no bundle is provided the bundle will be discovered from the JsDelivr CDN.
#### vite
For vite, create the following.
```typescript
import DuckDB from '@jetblack/duckdb-react'
import { DuckDBBundles } from '@duckdb/duckdb-wasm'
import duckdbMvpWasm from '@duckdb/duckdb-wasm/dist/duckdb-mvp.wasm?url'
import duckdbMvpWorker from '@duckdb/duckdb-wasm/dist/duckdb-browser-mvp.worker.js?url'
import duckdbEHWasm from '@duckdb/duckdb-wasm/dist/duckdb-eh.wasm?url'
import duckdbEHWorker from '@duckdb/duckdb-wasm/dist/duckdb-browser-eh.worker.js?url'
const VITE_BUNDLES: DuckDBBundles = {
mvp: {
mainModule: duckdbMvpWasm,
mainWorker: duckdbMvpWorker
},
eh: {
mainModule: duckdbEHWasm,
mainWorker: duckdbEHWorker
}
}
export default function App() {
return (
...
)
}
```
#### webpack
For webpack, create the following `bundle.ts`.
```typescript bundle.js
import DuckDB from '@jetblack/duckdb-react'
import { DuckDBBundles } from '@duckdb/duckdb-wasm'
import duckdbMvpWasm from '@duckdb/duckdb-wasm/dist/duckdb-mvp.wasm'
import duckdbEHWasm from '@duckdb/duckdb-wasm/dist/duckdb-eh.wasm'
const WEBPACK_BUNDLES: DuckDBBundles = {
mvp: {
mainModule: duckdbMvpWasm,
mainWorker: new URL('@duckdb/duckdb-wasm/dist/duckdb-browser-mvp.worker.js', import.meta.url).toString(),
},
eh: {
mainModule: duckdbEHWasm,
mainWorker: new URL('@duckdb/duckdb-wasm/dist/duckdb-browser-eh.worker.js', import.meta.url).toString(),
}
}
export default function App() {
return (
...
)
}
```