feat(#351 | create hypergraph): buildout create-hypergraph cli tool to scaffold a Hypergraph-enabled app (#364)

Author: cmwhited

.changeset/shaggy-cups-scream.md

@@ -0,0 +1,6 @@
+---
+"create-hypergraph": patch
+---
+
+Add CHANGELOG.md to publishable dist folder
+  

.github/workflows/tests-and-checks.yml

@@ -24,6 +24,10 @@ jobs:
         run: pnpm build
       - name: Generate Prisma Types
         run: cd apps/server && pnpm prisma generate
+      - name: Configure Git for tests
+        run: |
+          git config --global user.email "[email protected]"
+          git config --global user.name "Test User"
       - name: Typecheck
         run: pnpm check
       - name: Linting & Formatting

CONTRIBUTING.md

@@ -47,6 +47,13 @@ cd apps/typesync
 pnpm dev:client
 ```
 
+To develop the create-hypergraph, run:
+
+```sh
+cd apps/create-hypergraph
+pnpm run dev
+```
+
 You can run the Next example app with:
 
 ```sh

apps/connect/package.json

@@ -24,7 +24,7 @@
     "@tanstack/react-router-devtools": "^1.122.0",
     "@xstate/store": "^3.5.1",
     "clsx": "^2.1.1",
-    "effect": "^3.16.16",
+    "effect": "^3.17.0",
     "framer-motion": "^12.10.1",
     "graphql-request": "^7.2.0",
     "lucide-react": "^0.508.0",
@@ -37,7 +37,7 @@
   "devDependencies": {
     "@tailwindcss/vite": "^4.1.10",
     "@tanstack/router-plugin": "^1.120.2",
-    "@types/node": "^22.15.15",
+    "@types/node": "^24.1.0",
     "@types/react": "^19.1.3",
     "@types/react-dom": "^19.1.3",
     "@vitejs/plugin-react": "^4.4.1",

apps/create-hypergraph-app/README.md

@@ -0,0 +1,20 @@
+# create-hypergraph
+
+## 0.0.2
+### Patch Changes
+
+- 2d3814e: better check for access to template directory
+- 97894a1: test suite for Cli tool
+- f54e72a: create llms.txt for create-hypergraph usage
+- 4446ffe: resolve inputs from passed in options or prompts
+- f40426b: fix typo
+- ba47d53: rename package.json bin to create-hypergraph
+- 447cdb4: rename to create-hypergraph (drop app)
+- bd88912: handle sigint of user killing cli with a log line instead of error message
+- deee18d: add create-hypergraph-app tests to root workspace
+- 39beee4: fixes. updates from testing
+- 68a79db: rebase main. sort order import
+- 64d196d: buildout ability scaffold app, install deps, initialize git
+- 8ea798f: bump @types/node to latest
+- a004e4f: use prompts instead of options
+- 5a4c193: working on building create-hypergraph-app cli tool

apps/create-hypergraph-app/package.json

@@ -0,0 +1,67 @@
+# @graphprotocol/create-hypergraph-app
+
+CLI toolchain to scaffold a [Hypergraph-enabled](https://github.com/graphprotocol/hypergraph) application with a given template.
+
+Inspiration takes from the `vite`, `nextjs`, and `effect` create app command tools.
+
+## Scaffolding a hypergraph app
+
+With NPM:
+
+```bash
+npm create hypergraph@latest
+```
+
+With Yarn:
+
+```bash
+yarn create hypergraph
+```
+
+With PNPM:
+
+```bash
+pnpm create hypergraph@latest
+```
+
+With Bun:
+
+```bash
+bun create hypergraph
+```
+
+Then follow the given prompts.
+
+### Args
+
+- `app-name` -> if provided, used as the name of the app, as well as the directory the app is scaffolded in to
+
+### Params
+
+- `--template` -> if provided, uses the provided template
+  - options:
+    - vite-react
+- `--package-manager` -> if provided, uses the provided package manager
+  - options:
+    - pnpm
+    - bun
+    - npm
+    - yarn
+- `--skip-install-deps` -> if flag provided, the deps will not be install in the scaffolded app
+  - default: false
+- `--skip-initialize-git` -> if flag provided, git will not be initialized in the scaffolded app
+  - default: false
+
+```bash
+# fully configured
+pnpm create hypergraph@latest --template vite-react --package-manager pnpm my-hypergraph-app
+```
+
+### Currently Supported Templates
+
+- vite + react
+
+## References
+
+- [create vite app](https://github.com/vitejs/vite/tree/main/packages/create-vite)
+- [create effect app](https://effect.website/docs/getting-started/create-effect-app/)

apps/create-hypergraph/CHANGELOG.md

@@ -0,0 +1,131 @@
+# create-hypergraph
+
+A command-line tool for scaffolding Hypergraph-enabled applications.
+
+## What is Hypergraph?
+
+Hypergraph is a local-first framework for building web3 consumer applications. It enables developers to build performant, privacy-preserving apps where:
+
+- Data is stored locally on the user's device with zero network latency
+- All private data is end-to-end encrypted
+- Changes sync automatically across devices when online
+- Users own their data and can take it between apps
+- No traditional backend infrastructure is needed
+
+## When to Use Hypergraph
+
+Use Hypergraph when building:
+- **Collaborative Applications**: Real-time document editing, shared workspaces, team tools
+- **Social Applications**: Messaging apps, social networks, community platforms  
+- **Knowledge Management**: Note-taking apps, personal wikis, research tools
+- **Privacy-First Apps**: Any application requiring end-to-end encryption
+- **Offline-First Apps**: Applications that must work without internet connectivity
+
+Hypergraph is ideal when you need:
+- Instant UI updates without loading spinners
+- Real-time collaboration features
+- User-owned, portable data
+- Privacy through encryption
+- To avoid managing servers and databases
+
+## Installation and Usage
+
+This tool is published to npm and can be run using:
+```bash
+pnpm create hypergraph
+# or
+npm create hypergraph
+# or
+yarn create hypergraph
+# or
+bun create hypergraph
+```
+
+Alternatively, you can use the shorthand:
+```bash
+pnpx ch
+```
+
+## Purpose
+
+create-hypergraph is a CLI tool that scaffolds new Hypergraph-enabled applications with pre-configured templates. It streamlines the process of setting up a new project with The Graph Protocol's Hypergraph framework.
+
+## Command-Line Options
+
+### Positional Arguments
+
+- `app-name` (optional): The name of your application. This will also be the folder name where your app is scaffolded. If not provided, the tool will prompt for it interactively.
+
+### Options
+
+- `--template, -t` (optional): Template to scaffold
+  - Available values: `vite-react`
+  - Default: prompts user to select
+  - Currently only supports `vite-react` which scaffolds a Vite + React app using @tanstack/react-router
+
+- `--package-manager, -p` (optional): The package manager to use for installing dependencies
+  - Available values: `pnpm`, `bun`, `yarn`, `npm`
+  - Default: prompts user to select
+
+- `--skip-install-deps`: Skip installing dependencies after scaffolding
+  - Default: false (dependencies will be installed)
+
+- `--skip-initialize-git`: Skip initializing a git repository in the scaffolded app
+  - Default: false (git repository will be initialized with an initial commit)
+
+## Examples
+
+### Interactive Mode (Recommended)
+```bash
+pnpm create hypergraph
+```
+This will prompt you for all necessary information.
+
+### Fully Specified
+```bash
+pnpm create hypergraph my-app --template vite-react --package-manager pnpm
+```
+
+### Skip Optional Steps
+```bash
+pnpm create hypergraph my-app --skip-install-deps --skip-initialize-git
+```
+
+## Workflow
+
+1. **Validates app name**: Ensures the provided name is a valid project name
+2. **Checks target directory**: Verifies the directory doesn't exist or is empty
+3. **Copies template files**: Scaffolds the selected template into the target directory
+4. **Updates package.json**: Sets the correct package name in the scaffolded app
+5. **Initializes git** (optional): Creates a git repository with initial commit
+6. **Installs dependencies** (optional): Runs the package manager install command
+
+## Template Details
+
+### vite-react
+- Modern React application using Vite as the build tool
+- Configured with @tanstack/react-router for routing
+- Hypergraph integration pre-configured
+- TypeScript enabled
+- Development server with HMR
+
+## Error Handling
+
+The tool will fail gracefully if:
+- The target directory exists and is not empty
+- The selected template doesn't exist
+- Git initialization fails
+- Dependency installation fails
+
+## Requirements
+
+- Node.js >= 20
+- One of the supported package managers (pnpm, npm, yarn, or bun)
+
+## Post-Scaffolding
+
+After successful scaffolding, navigate to your app directory and start development:
+```bash
+cd <app-name>
+pnpm run dev  # or npm/yarn/bun run dev
+```