https://github.com/getditto/react-ditto
React wrappers for Ditto for easy integration using both components or hooks
https://github.com/getditto/react-ditto
Last synced: 3 months ago
JSON representation
React wrappers for Ditto for easy integration using both components or hooks
- Host: GitHub
- URL: https://github.com/getditto/react-ditto
- Owner: getditto
- Created: 2021-08-06T23:30:11.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2026-03-20T15:29:17.000Z (3 months ago)
- Last Synced: 2026-04-04T01:44:29.069Z (3 months ago)
- Language: TypeScript
- Homepage: https://getditto.github.io/react-ditto/
- Size: 3.66 MB
- Stars: 41
- Watchers: 29
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# React Wrapper Library for Ditto
[](http://www.typescriptlang.org/)
This is a React wrapper library for [Ditto](https://www.ditto.live).
Currently, this project works in web browsers, Node.JS and Electron environments. This project will soon have support for React Native environments. Please reach out to us using the email address below if you are interested in support for React Native.
If you have questions about this project or require any assistance, please get in touch via [contact@ditto.live](contact@ditto.live).
## Installation
1. Install this library with npm or yarn:
```
npm install @dittolive/ditto @dittolive/react-ditto
```
or with yarn
```
yarn add @dittolive/ditto @dittolive/react-ditto
```
2. At the top level of your react app, wrap it with any of the context providers provided: `DittoProvider` or `DittoLazyProvider`, like so:
```tsx
{({ loading, error }) => {
if (loading) return Loading Ditto...
if (error)
return (
There was an error loading Ditto. Error: {error.toString()}
)
return
}}
```
At this point you're ready to build your Ditto app using all of the helper hooks provided by the library. If you want to learn more, read the following sections to learn how to choose between `DittoProvider` and `DittoLazyProvider`, how to create Ditto identities, and how to use the hooks provided by this library.
## Choosing a Provider
The Ditto React library includes two different context providers which you can use in order to initialize the Ditto context for your app: `DittoProvider` and `DittoLazyProvider`.
`DittoProvider` should be used when the set of Ditto instances that will be used by your app are known beforehand. This is by far the simplest use case where an app uses a single or a few Ditto instances well known beforehand, that can be initialized statically when the app is bootstrapped. In all other cases, the `DittoLazyProvider` can be used to lazily create Ditto instances, such that instances will only be created if a child of the Ditto provider requires them and the instance doesn't exist inside of the provider.
The API for both providers is very similar and only differs for the `setup` prop, which returns `Ditto | Ditto[]` for `DittoProvider` and `Promise` for `DittoLazyProvider`.
It is important to highlight that choosing one provider or the other has no effect on the remaining hooks provided by the library. All hooks can be used in the same way, regardless of the type of provider that you choose to configure inside your app.
### DittoProvider Example
```tsx
const createDittoInstance = () => {
const ditto = new Ditto(createIdentity(), 'some-path')
ditto.startSync()
return ditto
}
;
{({ loading, error }) => {
if (loading) return Loading Ditto...
if (error)
return (
There was an error loading Ditto. Error: {error.toString()}
)
return
}}
```
### DittoLazyProvider Example
```tsx
const createDittoInstance = async (path) => {
let identity
if (path === 'path-1') {
identity = await getIdentityForPath1()
} else if (path === 'path-2') {
identity = await getIdentityForPath2()
}
if (identity) {
const ditto = new Ditto(createIdentity(), path)
ditto.startSync()
return ditto
} else {
return Promise.resolve(null)
}
}
;
{({ loading, error }) => {
if (loading) return Loading Ditto...
if (error)
return (
There was an error loading Ditto. Error: {error.toString()}
)
return
}}
```
## Creating Identities
Ditto instances are created by providing an `Identity` object to the Ditto constructor. Identities can be of several different types,
and can be created manually as JS objects, or using the identity hooks (`useOfflinePlaygroundIdentity`, `useOnlineIdentity`, `useOnlinePlaygroundIdentity`), which also makes it easier to configure authentication for your
apps:
### Offline Identities
```ts
const { create } = useOfflinePlaygroundIdentity()
const createDittoInstance = (forPath: string) => {
// Example of how to create an offline playground instance
const dittoPlaygroundIdentity = new Ditto(
create({
// If you're using the Ditto cloud, this ID should be the app ID shown on your app settings page on the portal.
appID: uuidv4(),
siteID: 123,
}),
forPath,
)
dittoPlaygroundIdentity.startSync()
return dittoPlaygroundIdentity
}
```
### Online Identities
```ts
const { create, getAuthenticationRequired, getTokenExpiresInSeconds } =
useOnlineIdentity()
const createDittoInstance = (forPath: string) => {
// Example of how to create an online instance with authentication enabled
const dittoOnline = new Ditto(
create(
{
// If you're using the Ditto cloud, this ID should be the app ID shown on your app settings page on the portal.
appID: uuidv4(),
enableDittoCloudSync: true,
},
forPath,
),
forPath,
)
dittoOnline.startSync()
return dittoOnline
}
```
```ts
const { create } = useOnlinePlaygroundIdentity()
const createDittoInstance = (forPath: string) => {
// Example of how to create an online playground instance
const dittoOnline = new Ditto(
create({
// If you're using the Ditto cloud, this ID should be the app ID shown on your app settings page on the portal.
appID: uuidv4(),
// If you're using the Ditto cloud, this token should be the Online Playground Authentication Token shown on your app settings page on the portal.
token: 'my-token',
}),
forPath,
)
dittoOnline.startSync()
return dittoOnline
}
```
You can find more information on working with online apps [here](#working-with-online-apps)
## Quick Start with `vite`
This is a quick guide on using Ditto with `vite` builds.
1. Install this library with npm or yarn
```
npm install @dittolive/ditto @dittolive/react-ditto
```
or with yarn
```
yarn add @dittolive/ditto @dittolive/react-ditto
```
2. In `./src/index.js`, or `./src/index.tsx` if you're using typescript, setup Ditto with the `DittoProvider` like so:
```tsx
// ... other imports from vite above
import { Ditto } from '@dittolive/ditto'
import {
DittoProvider,
useOnlinePlaygroundIdentity,
} from '@dittolive/react-ditto'
/**
* This configuration is optional for web browser-based react applications. This
* tells the `DittoProvider` where it should load the .wasm file. If no path is
* provided (ie. initOptions is undefined), the wasm will be loaded from our
* CDN. If you enable this, make sure to serve the `ditto.wasm` file with the
* correct MIME type and CORS headers. See
* https://www.npmjs.com/package/@dittolive/ditto#browser-environments for
* details.
**/
const initOptions = {
webAssemblyModule: '/ditto.wasm',
}
/** Example of a React root component setting up a single ditto instance that uses a development connection */
const RootComponent = () => {
const { create } = useOnlinePlaygroundIdentity()
return (
{
const ditto = new Ditto(
create({
// Create an app on https://portal.ditto.live/ and follow the
// instructions to get your token. Replace the placeholders below
// with your app id and token.
appID: 'your-app-id',
token: 'your-online-playground-token',
}),
'testing',
)
await ditto.disableSyncWithV3()
ditto.startSync()
return ditto
}}
/* initOptions={initOptions} */
>
{({ loading, error }) => {
if (loading) return
Loading
if (error) return {error.message}
return
}}
)
}
const root = ReactDOM.createRoot(document.getElementById('root'))
root.render(
,
)
```
3. In your `App` component, you can now use hooks like `usePendingCursorOperation` or `usePendingIDSpecificOperation` to get your documents like so:
```tsx
import { usePendingCursorOperation, useMutations } from '@dittolive/react-ditto'
export default function App() {
const { documents } = usePendingCursorOperation({
collection: 'tasks',
})
const { removeByID, upsert } = useMutations({ collection: 'tasks' })
return (
<>
upsert({ value: { text: 'Hello' } })}>
Add Task
-
{JSON.stringify(doc.value)}
removeByID({ _id: doc.id })}>remove
{documents.map((doc) => (
))}
>
)
}
```
Alternatively, you can also choose to go with the lazy variants of these hooks (`useLazyPendingCursorOperation` and `useLazyPendingIDSpecificOperation`), in order to launch queries on the data store as a response to a user event:
```tsx
import { useLazyPendingCursorOperation } from '@dittolive/react-ditto'
export default function App() {
const { documents, exec } = useLazyPendingCursorOperation()
if (!documents?.length) {
return (
exec({ collection: 'tasks' })}>
Click to load!
)
}
return (
- {JSON.stringify(doc.value)}
{documents.map((doc) => (
))}
)
}
```
## Working with Online apps
Using the [Portal](http://portal.ditto.live) you can create apps that sync to the cloud. If you're just getting started with Ditto and want to experiment without authentication, you may use the `useOnlinePlaygroundIdentity` hook to create an `onlinePlayground` identity type. This **should not** be used in production environments. Otherwise, online apps must be created with an `onlineWithAuthentication` identity type, for which the `useOnlineIdentity` hook can be used. The `useOnlineIdentity` hook helps you create online Ditto instances that sync with the cloud, following these steps:
```tsx
/** Example of a React root component setting up a single ditto instance that uses a development connection */
import { useEffect } from 'react'
const RootComponent = () => {
const { create, getAuthenticationRequired, getTokenExpiresInSeconds } =
useOnlineIdentity()
return (
<>
{
const ditto = new Ditto(
create(
{ appID: 'your-app-id', path: '/my-online-path' },
'/my-online-path',
),
)
ditto.startSync()
return ditto
}}
/*initOptions={initOptions} */
>
{({ loading, error, ditto }) => {
if (loading) return
Loading
if (error) return
{error.message}
return
}}
>
)
}
const App = () => {
const ditto = useDitto()
useEffect(() => {
if (ditto) {
ditto.auth
.loginWithToken('token', 'provider')
.then(() => console.log('Login successful'))
}
}, [ditto])
return
}
```
For Online apps, the `useOnlineIdentity` hook returns the following set of properties that can be used to manage authentication for your app:
- `create`: Creates an `onlineWithAuthentication` object preconfigured such that the hook can manage the authentication flow using the exposed `authenticate` function.
- `getAuthenticationRequired`: Is a function that takes in the app path for which to check the authentication required state, and will return true if your Ditto instance is requiring the current user to authenticate with the app. You can configure authentication webhooks on the [Portal](http://portal.ditto.live), from your app settings area, in order to provide your own set of validation services for your app.
- `getTokenExpiresInSeconds`: Is a function that takes in the app path for which to check the token expiry second, and returns the number of seconds in which your current token expires if this has been reported by the Ditto SDK.
## Building this library and running tests
- **Building:** run `npm run build` or `yarn build`.
- **Run Tests:** run `npm test` or `yarn test`
- **Generating Documentation Website Files** run `npm run docs:generate`
## Running example apps.
Each example project is in its own directory underneath the [./examples](./examples) directory.