feat(#352 | Typesync v2): buildout typesync-studio as a distributable cli/ui tool from hypergraph

.changeset/tame-horses-try.md

@@ -0,0 +1,13 @@
+---
+"@graphprotocol/hypergraph": minor
+---
+
+Introduced a cli tool and typesync studio UI to let users graphically visualize, update, and publish their hypergraph schemas.
+
+1. install the latest `@graphprotocol/hypergraph` version: `pnpm add @graphprotocol/hypergraph@latest`
+2. add a script to your `package.json` to open the typesync studio: `"typesync": "hg typesync --open"`
+3. open your browser to http://localhost:3000
+4. view your current Hypergraph app schema, parsed from your `schema.ts` file
+5. update your schema, view existing types and properties on the Knowledge Graph. add types and properties.
+6. sync your schema updates to your schema.ts file
+7. publish your schema to the Knowledge Graph.

.vscode/settings.json

@@ -1,4 +1,13 @@
 {
+  "files.watcherExclude": {
+    "**/routeTree.gen.ts": true
+  },
+  "search.exclude": {
+    "**/routeTree.gen.ts": true
+  },
+  "files.readonlyInclude": {
+    "**/routeTree.gen.ts": true
+  },
   "editor.formatOnSave": true,
   "editor.codeActionsOnSave": {
     "source.organizeImports.biome": "explicit"

apps/connect/package.json

@@ -25,10 +25,10 @@
     "@tanstack/react-router-devtools": "^1.122.0",
     "@xstate/store": "^3.5.1",
     "clsx": "^2.1.1",
-    "effect": "^3.17.3",
+    "effect": "^3.17.6",
     "graphql-request": "^7.2.0",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
     "tailwind-merge": "^3.3.1",
     "viem": "^2.30.6",
     "vite": "^6.3.5"
@@ -37,8 +37,8 @@
     "@tailwindcss/vite": "^4.1.11",
     "@tanstack/router-plugin": "^1.120.2",
     "@types/node": "^24.1.0",
-    "@types/react": "^19.1.3",
-    "@types/react-dom": "^19.1.3",
+    "@types/react": "^19.1.9",
+    "@types/react-dom": "^19.1.7",
     "@vitejs/plugin-react": "^4.4.1",
     "prettier": "^3.6.2",
     "prettier-plugin-tailwindcss": "^0.6.14",

apps/create-hypergraph/package.json

@@ -55,15 +55,15 @@
   "homepage": "https://github.com/graphprotocol/hypergraph/tree/main/apps/create-hypergraph-app#readme",
   "devDependencies": {
     "@effect/cli": "^0.69.0",
-    "@effect/language-service": "^0.31.2",
+    "@effect/language-service": "^0.34.0",
     "@effect/platform": "^0.90.0",
-    "@effect/platform-node": "^0.94.0",
+    "@effect/platform-node": "^0.94.1",
     "@effect/printer-ansi": "^0.45.0",
     "@effect/vitest": "^0.25.0",
-    "@types/node": "^24.1.0",
-    "effect": "^3.17.3",
+    "@types/node": "^24.2.0",
+    "effect": "^3.17.6",
     "execa": "^9.6.0",
-    "tsdown": "^0.13.0",
+    "tsdown": "^0.13.3",
     "tsx": "^4.20.3"
   }
 }

apps/create-hypergraph/template-nextjs/package.json

@@ -26,8 +26,8 @@
     "lucide-react": "^0.525.0",
     "next": "15.4.3",
     "postcss": "^8.5.6",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
     "tailwind-merge": "^3.3.1",
     "tailwindcss": "^4.1.11"
   },

apps/create-hypergraph/template-vite-react/package.json

@@ -21,20 +21,20 @@
     "@tanstack/react-router": "^1.129.2",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "effect": "^3.17.3",
+    "effect": "^3.17.6",
     "lucide-react": "^0.525.0",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
     "tailwind-merge": "^3.3.1",
     "tailwindcss": "^4.1.11",
     "vite": "^7.0.5"
   },
   "devDependencies": {
     "@eslint/js": "^9.31.0",
     "@tanstack/router-plugin": "^1.129.2",
-    "@types/node": "^24.1.0",
-    "@types/react": "^19.1.8",
-    "@types/react-dom": "^19.1.6",
+    "@types/node": "^24.2.0",
+    "@types/react": "^19.1.9",
+    "@types/react-dom": "^19.1.7",
     "@vitejs/plugin-react": "^4.7.0",
     "eslint": "^9.31.0",
     "eslint-plugin-react-hooks": "^5.2.0",

apps/events/package.json

@@ -23,13 +23,13 @@
     "@xstate/store": "^3.5.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "effect": "^3.17.3",
+    "effect": "^3.17.6",
     "framer-motion": "^12.10.1",
     "graphql-request": "^7.1.2",
     "isomorphic-ws": "^5.0.0",
     "lucide-react": "^0.508.0",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
     "react-select": "^5.10.1",
     "siwe": "^3.0.0",
     "tailwind-merge": "^3.2.0",
@@ -42,9 +42,9 @@
     "@biomejs/biome": "1.9.4",
     "@tailwindcss/vite": "^4.1.5",
     "@tanstack/router-plugin": "^1.120.2",
-    "@types/node": "^24.1.0",
-    "@types/react": "^19.1.3",
-    "@types/react-dom": "^19.1.3",
+    "@types/node": "^24.2.0",
+    "@types/react": "^19.1.9",
+    "@types/react-dom": "^19.1.7",
     "@types/uuid": "^10.0.0",
     "@vitejs/plugin-react": "^4.4.1",
     "globals": "^16.1.0",

apps/events/src/mapping.ts

@@ -1,15 +1,43 @@
-import type { Mapping } from '@graphprotocol/hypergraph';
 import { Id } from '@graphprotocol/hypergraph';
+import type { Mapping } from '@graphprotocol/hypergraph/mapping';
 
-export const mapping: Mapping.Mapping = {
-  Event: {
-    typeIds: [Id('7f9562d4-034d-4385-bf5c-f02cdebba47a')],
+export const mapping: Mapping = {
+  User: {
+    typeIds: [Id('bffa181e-a333-495b-949c-57f2831d7eca')],
     properties: {
-      name: Id('a126ca53-0c8e-48d5-b888-82c734c38935'),
-      description: Id('9b1f76ff-9711-404c-861e-59dc3fa7d037'),
+      name: Id('c9c79675-850a-42c5-bbbd-9e5c55d3f4e7'),
+      created: Id('f8df1caf-14b4-4c1e-85fb-4e97f7d7070a'),
+    },
+  },
+  Todo: {
+    typeIds: [Id('44fe82a9-e4c2-4330-a395-ce85ed78e421')],
+    properties: {
+      name: Id('c668aa67-bbca-4b2c-908c-9c5599035eab'),
+      completed: Id('71e7654f-2623-4794-88fb-841c8f3dd9b4'),
     },
     relations: {
-      sponsors: Id('6860bfac-f703-4289-b789-972d0aaf3abe'),
+      assignees: Id('5b80d3ee-2463-4246-b628-44ba808ab3e1'),
+    },
+  },
+  Todo2: {
+    typeIds: [Id('210f4e94-234c-49d7-af0f-f3b74fb07650')],
+    properties: {
+      name: Id('e291f4da-632d-4b70-aca8-5c6c01dbf1ca'),
+      checked: Id('d1cc82ef-8bde-45f4-b31c-56b6d59279ec'),
+      due: Id('6a28f275-b31c-47bc-83cd-ad416aaa7073'),
+      amount: Id('0c8219be-e284-4738-bd95-91a1c113c78e'),
+      point: Id('7f032477-c60e-4c85-a161-019b70db05ca'),
+      website: Id('75b6a647-5c2b-41e7-92c0-b0a0c9b28b02'),
+    },
+    relations: {
+      assignees: Id('1115e9f8-db2e-41df-8969-c5d34c367c10'),
+    },
+  },
+  JobOffer: {
+    typeIds: [Id('f60585af-71b6-4674-9a26-b74ca6c1cceb')],
+    properties: {
+      name: Id('a126ca53-0c8e-48d5-b888-82c734c38935'),
+      salary: Id('baa36ac9-78ac-4cf7-8394-6b2d3006bebe'),
     },
   },
   Company: {
@@ -21,32 +49,24 @@ export const mapping: Mapping.Mapping = {
       jobOffers: Id('1203064e-9741-4235-89d4-97f4b22eddfb'),
     },
   },
-  JobOffer: {
-    typeIds: [Id('f60585af-71b6-4674-9a26-b74ca6c1cceb')],
+  Event: {
+    typeIds: [Id('7f9562d4-034d-4385-bf5c-f02cdebba47a')],
     properties: {
       name: Id('a126ca53-0c8e-48d5-b888-82c734c38935'),
-      salary: Id('baa36ac9-78ac-4cf7-8394-6b2d3006bebe'),
+      description: Id('9b1f76ff-9711-404c-861e-59dc3fa7d037'),
+      createdAt: Id('e2e6906b-d2b6-48d2-8aa2-54e8b29f6933'),
+      updatedAt: Id('2e877fe0-a504-4ea0-b43c-210d011db434'),
+    },
+    relations: {
+      sponsors: Id('6860bfac-f703-4289-b789-972d0aaf3abe'),
+    },
+  },
+  Todo3: {
+    typeIds: [Id('4f7bba76-7855-4d63-b59d-1d9f2be866df')],
+    properties: {
+      name: Id('47006386-d351-411c-8287-1dae1c1aa8c1'),
+      completed: Id('9f9f00eb-4f32-4f71-92ba-b266566d0013'),
+      description: Id('89cac80a-1dbd-4bca-97b2-45e1556d9122'),
     },
   },
-
-  // Todo2: {
-  //   typeIds: [Id('LJuM8ju67mCv78FhAiK9k9')],
-  //   properties: {
-  //     name: Id('a126ca53-0c8e-48d5-b888-82c734c38935'),
-  //     checked: Id('Ud9kn9gAUsCr1pxvxcgDj8'),
-  //     due: Id('CFisPgjjWVdnaMtSWJDBqA'),
-  //     point: Id('BkcVo7JZHF5LsWw7XZJwwe'),
-  //     website: Id('XZmLQ8XyaUHnNWgSSbzaHU'),
-  //     amount: Id('LfzKTfgy5Qg3PxAfKB2BL7'),
-  //   },
-  //   relations: {
-  //     assignees: Id('HCdFcTRyMyZMXScKox738i'),
-  //   },
-  // },
-  // User: {
-  //   typeIds: [Id('Fk5qzwdpKsD35gm5ts4SZA')],
-  //   properties: {
-  //     name: Id('a126ca53-0c8e-48d5-b888-82c734c38935'),
-  //   },
-  // },
 };

apps/events/src/schema.ts

@@ -2,6 +2,7 @@ import { Entity, Type } from '@graphprotocol/hypergraph';
 
 export class User extends Entity.Class<User>('User')({
   name: Type.String,
+  created: Type.Date,
 }) {}
 
 export class Todo extends Entity.Class<Todo>('Todo')({
@@ -27,12 +28,19 @@ export class JobOffer extends Entity.Class<JobOffer>('JobOffer')({
 
 export class Company extends Entity.Class<Company>('Company')({
   name: Type.String,
-  // address: Type.String,
   jobOffers: Type.Relation(JobOffer),
 }) {}
 
 export class Event extends Entity.Class<Event>('Event')({
   name: Type.String,
-  description: Type.optional(Type.String),
+  description: Type.String,
   sponsors: Type.Relation(Company),
+  createdAt: Type.Date,
+  updatedAt: Type.Date,
+}) {}
+
+export class Todo3 extends Entity.Class<Todo3>('Todo3')({
+  name: Type.String,
+  completed: Type.Boolean,
+  description: Type.String,
 }) {}

apps/next-example/package.json

@@ -15,8 +15,8 @@
     "@graphprotocol/hypergraph": "workspace:*",
     "@graphprotocol/hypergraph-react": "workspace:*",
     "next": "15.3.2",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1"
   },
   "devDependencies": {
     "@types/node": "^22",

apps/server/package.json

@@ -19,7 +19,7 @@
     "@privy-io/server-auth": "^1.26.0",
     "body-parser": "^2.2.0",
     "cors": "^2.8.5",
-    "effect": "^3.17.3",
+    "effect": "^3.17.6",
     "express": "^5.1.0",
     "prisma": "^6.7.0",
     "siwe": "^3.0.0",
@@ -29,7 +29,7 @@
   "devDependencies": {
     "@types/cors": "^2.8.17",
     "@types/express": "^5.0.1",
-    "@types/node": "^24.1.0",
+    "@types/node": "^24.2.0",
     "@types/pg": "^8.15.0",
     "@types/ws": "^8.18.1",
     "tsup": "^8.4.0",

biome.jsonc

@@ -17,7 +17,8 @@
       "!**/tsconfig.*.json",
       "!**/variant-schema.ts",
       "!**/apps/create-hypergraph/template-*/**",
-      "!**/*.css"
+      "!**/*.css",
+      "!packages/hypergraph/typesync-studio/src/generated/**/*.ts"
     ]
   },
   "formatter": {

docs/package.json

@@ -19,8 +19,8 @@
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1"
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "3.8.1",

packages/hypergraph-react/package.json

@@ -37,20 +37,20 @@
     "@graphprotocol/hypergraph": "workspace:*",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",
-    "@types/react": "^19.1.3",
-    "@vitejs/plugin-react": "^4.4.1",
+    "@types/react": "^19.1.9",
+    "@vitejs/plugin-react": "^4.7.0",
     "@xstate/store": "^3.5.1",
     "jsdom": "^26.1.0",
-    "react": "^19.1.0"
+    "react": "^19.1.1"
   },
   "dependencies": {
-    "@automerge/automerge": "^2.2.9",
-    "@automerge/automerge-repo": "^2.0.6",
-    "@automerge/automerge-repo-react-hooks": "^2.0.6",
+    "@automerge/automerge": "^3.1.1",
+    "@automerge/automerge-repo": "^2.2.0",
+    "@automerge/automerge-repo-react-hooks": "^2.2.0",
     "@graphprotocol/grc-20": "^0.24.1",
     "@noble/hashes": "^1.8.0",
     "@tanstack/react-query": "^5.75.5",
-    "effect": "^3.17.3",
+    "effect": "^3.17.6",
     "graphql-request": "^7.1.2",
     "siwe": "^3.0.0",
     "uuid": "^11.1.0",

packages/hypergraph-react/src/HypergraphAppContext.tsx

@@ -1,9 +1,7 @@
 'use client';
 
-// @ts-expect-error not properly typed and exported in the automerge package
-import { automergeWasmBase64 } from '@automerge/automerge/automerge.wasm.base64.js';
+import { automergeWasmBase64 } from '@automerge/automerge/automerge.wasm.base64';
 import * as automerge from '@automerge/automerge/slim';
-import { uuid } from '@automerge/automerge/slim';
 import type { DocHandle } from '@automerge/automerge-repo';
 import { Repo } from '@automerge/automerge-repo/slim';
 import { RepoContext } from '@automerge/automerge-repo-react-hooks';
@@ -36,6 +34,7 @@ import {
   useRef,
   useState,
 } from 'react';
+import { v4 as uuid } from 'uuid';
 import type { Address, Hex } from 'viem';
 
 const decodeResponseMessage = Schema.decodeUnknownEither(Messages.ResponseMessage);