NextGraph React Expense Tracker Example with Discrete JSON Documents

A complete example app demonstrating the NextGraph Discrete (Yjs/Automerge) ORM SDK in React. Changes are immediately persisted and synced with other devices. All data is encrypted.

This README walks you through the features of the SDK and how to build your own NextGraph-powered application.

You can find examples for Vue and Svelte frontends and the RDF (graph) ORM here.

---

Table of Contents

• NextGraph React Expense Tracker Example with Discrete JSON Documents
  • Table of Contents
  • Quick Start
  • Project Structure
  • Building Your Own App
    • Step 1: Install Dependencies
    • Step 2: Initialization
    • Step 3: Use the Data in the Components
  • About NextGraph
  • License

---

Quick Start

Create a wallet at https://nextgraph.eu and log in once with your password.

Clone this repo:

# Clone the repository
git clone https://git.nextgraph.org/NextGraph/expense-tracker-discrete-react.git
cd expense-tracker-discrete-react

# Install dependencies
pnpm install

# Run the development server:
# If you want to use a YJS CRDT:
pnpm dev-yjs
# or if you want to use an Automerge CRDT:
pnpm dev-automerge

In Chrome, there are new restrictions for a public website including an iframe to localhost. And that's what we do here in third party mode, when you are developing your app with vite on localhost. The first time you will load the page, a popup will appear, asking you: "nextgraph.eu wants to look for and connect to any device on your local network". You should click on "Allow". If you get a gray screen, click on the recycle icon that is on the right side of the blue thin banner. Then you should be all good. If not, you have to go to chrome://flags/#local-network-access-check and select Disabled. This dev env issue has no impact on your production app deployed on your own domain, specially if you host your app with TLS.

• Open the URL displayed in the console. You'll be redirected to NextGraph to authenticate with your wallet, then your app loads inside NextGraph's secure iframe.
• You can open the app in a second tab to see how the data is propagated.

---

Project Structure

src/
├── components/                # The app's components
│
├── utils/
│   ├── loadStore.ts           # Creates or loads the CRDT document with your data
│   ├── ngSession.ts           # NextGraph session initialization
│   └── useDocumentStore.ts    # Hook that's used in the components to get the document data
└── types.ts                   # Types for the data store

---

Building Your Own App

If you want to create your own app, clone this repo or walk through the following steps.

Step 1: Install Dependencies

pnpm add @ng-org/web@latest @ng-org/orm@latest
# Or npm install / yarn add / ...

Package	Purpose
@ng-org/web	Core NextGraph SDK for web applications
@ng-org/orm	Core ORM utilities
@ng-org/orm/react	react framework-specific hooks

Step 2: Initialization

Your app will run inside a NextGraph-controlled iframe. To make things easier for you, we created a utility file that handles initialization, see src/utils/ngSession.ts.

The file exports an init() function. When it is called outside of an iframe, it will redirected you to authenticate with your wallet. That's why you should call it as early as possible, to prevent shortly rendered pages directly followed by the redirect. In this app, we call it in index.html.

Now we have a session and need to load (and possibly create) a document. The document contains the data that we use for our application and that we subscribe to. You can see how this is done in src/utils/loadStore.ts.
In loadStore.ts, you can see how a subscription to the document is created that the application uses. To find the document id, a SPARQL graph query is made: To every document, you can attach RDF data. We leverage that here by attaching an application-specific quad (e.g. <documentId> <type> <did:ng:z:ExpenseTrackerDiscreteApp-Automerge>), to find the document again. Once we have the document id, we can create an ORM subscription. Note that creating the subscription here is strictly speaking not necessary. The useDiscrete hook that is introduced next can create a subscription by itself. If a subscription is open however, the hook will use that one. In our case, the subscription remains open throughout the application's lifetime and we don't need to wait for the initialization of a subscription again and again.

Step 3: Use the Data in the Components

In the hook useDocumentStore, you can see how we subscribe to the document that stores expenses and expense categories. Use the useDiscrete hook to create 2-way bindings between the engine and react. You can see that modifications to values of the returned doc will immediately update the component - no need for setState. Besides the rerender, the modified data is immediately persisted and will be synchronized with other applications and devices as well. When changes are coming from the engine (e.g. a different device made a change), the components rerender too.

When the subscription isn't established yet, doc will be undefined.

For an example, see src/components/Expenses.tsx and the ExpenseCard children.

For more advanced data and subscription management, e.g. transactions or component-independent stores, see the TS docs of @ng-org/orm (especially DiscreteOrmSubscription) and the reference.

About NextGraph

NextGraph brings about the convergence of P2P and Semantic Web technologies, towards a decentralized, secure and privacy-preserving cloud, based on CRDTs.

This open source ecosystem provides solutions for end-users (a platform) and software developers (a framework), wishing to use or create decentralized apps featuring: live collaboration on rich-text documents, peer to peer communication with end-to-end encryption, offline-first, local-first, portable and interoperable data, total ownership of data and software, security and privacy.

Centered on repositories containing semantic data (RDF), rich text, and structured data formats like JSON, synced between peers belonging to permissioned groups of users, it offers strong eventual consistency, thanks to the use of CRDTs. Documents can be linked together, signed, shared securely, queried using the SPARQL language and organized into sites and containers.

More info: https://nextgraph.org

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE2 or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.

SPDX-License-Identifier: Apache-2.0 OR MIT

---

NextGraph received funding through the NGI Assure Fund and the NGI Zero Commons Fund, both funds established by NLnet Foundation with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreements No 957073 and No 101092990, respectively.