create-tinybase 0.3.0 → 1.0.0

package/cli.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import{existsSync as w}from"fs";import{dirname as f,join as u}from"path";import{createCLI as k,detectPackageManager as x}from"tinycreate";import{fileURLToPath as R}from"url";const S=f(R(import.meta.url)),P={welcomeMessage:`\u{1F389} Welcome to TinyBase!
-`,questions:[{type:"text",name:"projectName",message:"Project name:",initial:"my-tinybase-app",validate:e=>{if(e.length===0)return"Project name is required";const t=u(process.cwd(),e);return w(t)?`Directory "${e}" already exists. Please choose a different name.`:!0}},{type:"select",name:"appType",message:"App type:",choices:[{title:"Todo app",value:"todos"},{title:"Chat app",value:"chat"},{title:"Drawing app",value:"drawing"},{title:"Tic-tac-toe game",value:"game"}],initial:0},{type:"select",name:"language",message:"Language:",choices:[{title:"TypeScript",value:"typescript"},{title:"JavaScript",value:"javascript"}],initial:0},{type:"select",name:"framework",message:"Framework:",choices:[{title:"React",value:"react"},{title:"Vanilla",value:"vanilla"}],initial:0},{type:(e,t)=>t.language==="typescript"?"confirm":null,name:"schemas",message:"Include store schemas?",initial:!1},{type:"select",name:"syncType",message:"Synchronization:",choices:[{title:"None",value:"none"},{title:"Via remote demo server (stateless)",value:"remote"},{title:"Via local node server (stateless)",value:"node"},{title:"Via local DurableObjects server (stateful)",value:"durable-objects"}],initial:1},{type:"select",name:"persistenceType",message:"Persistence:",choices:[{title:"None",value:"none"},{title:"Local Storage",value:"local-storage"},{title:"SQLite",value:"sqlite"},{title:"PGlite",value:"pglite"}],initial:1},{type:"confirm",name:"prettier",message:"Include Prettier?",initial:!0},{type:"confirm",name:"eslint",message:"Include ESLint?",initial:!0},{type:(e,t)=>t.syncType!=="node"&&t.syncType!=="durable-objects"?"confirm":null,name:"installAndRun",message:"Install dependencies and start dev server?",initial:!0}],createContext:e=>{const{projectName:t,language:s,framework:n,appType:o,prettier:m,eslint:g,schemas:l,syncType:d,persistenceType:y,installAndRun:p}=e,i=s==="typescript",v=!i,c=n==="react",T=i?c?"tsx":"ts":c?"jsx":"js",a=d||"remote",h=a!=="none",b=a==="node"||a==="durable-objects",j=a==="durable-objects"?"durable-objects":"node",r=y||"local-storage";return{projectName:t,language:s,framework:n,appType:o,prettier:m,eslint:g,schemas:i&&(l===!0||l==="true"),syncType:a,sync:h,server:b,serverType:j,persistenceType:r,persist:r!=="none",persistLocalStorage:r==="local-storage",persistSqlite:r==="sqlite",persistPglite:r==="pglite",installAndRun:p===!0||p==="true",typescript:i,javascript:v,react:c,ext:T}},createDirectories:async(e,t)=>{const{mkdir:s}=await import("fs/promises"),{join:n}=await import("path"),o=t.server;await s(n(e,"client/src"),{recursive:!0}),await s(n(e,"client/public"),{recursive:!0}),o&&await s(n(e,"server"),{recursive:!0})},getFiles:()=>[{template:"README.md.hbs",output:"README.md",prettier:!0}],processIncludedFile:(e,t)=>{const{javascript:s}=t,n=e.prettier??/\.(js|jsx|ts|tsx|css|json|html|md)$/.test(e.output),o=e.transpile??(/\.(ts|tsx)\.hbs$/.test(e.template)&&s===!0);return{...e,prettier:n,transpile:o}},templateRoot:u(S,"templates"),installCommand:"{pm} install",devCommand:"{pm} run dev",workingDirectory:"client",onSuccess:(e,t)=>{const s=t.syncType,n=s==="node"||s==="durable-objects",o=x();console.log("Next steps:"),console.log(),n&&(console.log("To run the server:"),console.log(`  cd ${e}/server`),console.log(`  ${o} install`),console.log(`  ${o} run dev`),console.log()),console.log("To run the client:"),console.log(`  cd ${e}/client`),console.log(`  ${o} install`),console.log(`  ${o} run dev`)}};k(P).catch(e=>{console.error(e),process.exit(1)});
+import{existsSync as f}from"fs";import{dirname as k,join as u}from"path";import{createCLI as x,detectPackageManager as R}from"tinycreate";import{fileURLToPath as S}from"url";const P=k(S(import.meta.url)),C={welcomeMessage:`\u{1F389} Welcome to TinyBase!
+`,questions:[{type:"text",name:"projectName",message:"Project name:",initial:"my-tinybase-app",validate:e=>{if(e.length===0)return"Project name is required";const t=u(process.cwd(),e);return f(t)?`Directory "${e}" already exists. Please choose a different name.`:!0}},{type:"select",name:"appType",message:"App type:",choices:[{title:"Todo app",value:"todos"},{title:"Chat app",value:"chat"},{title:"Drawing app",value:"drawing"},{title:"Tic-tac-toe game",value:"game"}],initial:0},{type:"select",name:"language",message:"Language:",choices:[{title:"TypeScript",value:"typescript"},{title:"JavaScript",value:"javascript"}],initial:0},{type:"select",name:"framework",message:"Framework:",choices:[{title:"React",value:"react"},{title:"Vanilla",value:"vanilla"}],initial:0},{type:(e,t)=>t.language==="typescript"?"confirm":null,name:"schemas",message:"Include store schemas?",initial:!1},{type:"select",name:"syncType",message:"Synchronization:",choices:[{title:"None",value:"none"},{title:"Via remote demo server (stateless)",value:"remote"},{title:"Via local node server (stateless)",value:"node"},{title:"Via local DurableObjects server (stateful)",value:"durable-objects"}],initial:1},{type:"select",name:"persistenceType",message:"Persistence:",choices:[{title:"None",value:"none"},{title:"Local Storage",value:"local-storage"},{title:"SQLite",value:"sqlite"},{title:"PGlite",value:"pglite"}],initial:1},{type:"confirm",name:"prettier",message:"Include Prettier?",initial:!0},{type:"confirm",name:"eslint",message:"Include ESLint?",initial:!0},{type:(e,t)=>t.syncType!=="node"&&t.syncType!=="durable-objects"?"confirm":null,name:"installAndRun",message:"Install dependencies and start dev server?",initial:!0}],createContext:e=>{const{projectName:t,language:s,framework:n,appType:o,prettier:m,eslint:g,schemas:l,syncType:d,persistenceType:y,installAndRun:p}=e,i=s==="typescript",v=!i,c=n==="react",b=i?c?"tsx":"ts":c?"jsx":"js",a=d||"remote",T=a!=="none",h=a==="node"||a==="durable-objects",j=a==="durable-objects"?"durable-objects":"node",w=a==="durable-objects",r=y||"local-storage";return{projectName:t,language:s,framework:n,appType:o,prettier:m,eslint:g,schemas:i&&(l===!0||l==="true"),syncType:a,sync:T,server:h,serverType:j,isDurableObject:w,persistenceType:r,persist:r!=="none",persistLocalStorage:r==="local-storage",persistSqlite:r==="sqlite",persistPglite:r==="pglite",installAndRun:p===!0||p==="true",typescript:i,javascript:v,react:c,ext:b}},createDirectories:async(e,t)=>{const{mkdir:s}=await import("fs/promises"),{join:n}=await import("path"),o=t.server;await s(n(e,"client/src"),{recursive:!0}),await s(n(e,"client/public"),{recursive:!0}),o&&await s(n(e,"server"),{recursive:!0})},getFiles:()=>[{template:"README.md.hbs",output:"README.md",prettier:!0}],processIncludedFile:(e,t)=>{const{javascript:s}=t,n=e.prettier??/\.(js|jsx|ts|tsx|css|json|html|md)$/.test(e.output),o=e.transpile??(/\.(ts|tsx)\.hbs$/.test(e.template)&&s===!0);return{...e,prettier:n,transpile:o}},templateRoot:u(P,"templates"),installCommand:"{pm} install",devCommand:"{pm} run dev",workingDirectory:"client",onSuccess:(e,t)=>{const s=t.syncType,n=s==="node"||s==="durable-objects",o=R();console.log("Next steps:"),console.log(),n&&(console.log("To run the server:"),console.log(`  cd ${e}/server`),console.log(`  ${o} install`),console.log(`  ${o} run dev`),console.log()),console.log("To run the client:"),console.log(`  cd ${e}/client`),console.log(`  ${o} install`),console.log(`  ${o} run dev`)}};x(C).catch(e=>{console.error(e),process.exit(1)});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-tinybase",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "author": "jamesgpearce",
   "repository": {
     "type": "git",
@@ -8,7 +8,7 @@
   },
   "license": "MIT",
   "homepage": "https://tinybase.org",
-  "description": "The CLI to build new apps using TinyBase, a reactive data store and sync engine.",
+  "description": "A command-line tool to create TinyBase apps with full synchronization and local-first capabilities.",
   "keywords": [
     "tiny",
     "sync engine",
@@ -16,7 +16,10 @@
     "reactive",
     "state",
     "data",
-    "react"
+    "react",
+    "sqlite",
+    "pglite",
+    "durable-objects"
   ],
   "type": "module",
   "bin": {

package/templates/README.md.hbs

@@ -9,8 +9,8 @@ A TinyBase app built with {{#if typescript}}TypeScript{{else}}JavaScript{{/if}}
 
 ## Getting Started
 
-Alongside this file, you will see a directory called `client`{{#if server}} (and optionally
-one called `server` for your {{#if (eq syncType "node")}}local Node.js server{{else if (eq syncType "durable-objects")}}local Cloudflare Durable Objects server{{/if}}){{/if}}.
+Alongside this file, you will see a directory called `client`{{#if server
+}} (and one called `server` for your {{#if (eq syncType "node")}}local Node.js server{{else if (eq syncType "durable-objects")}}local Cloudflare Durable Objects server{{/if}}){{/if}}.
 
 To start the web client with Vite, run the following commands:
 
@@ -37,6 +37,123 @@ PNPM, Yarn, and Bun should also work. Your app will be available at
 {{/if}}
 After that, start hacking!
 
+## Structure
+
+This project is organized into {{#if server}}two main directories{{else}}a single `client` directory{{/if}}:
+
+### Client
+
+The `client` directory contains your {{#if react}}React-based{{else}}vanilla JavaScript{{/if}} web application,
+built with Vite and {{#if typescript}}TypeScript{{else}}JavaScript{{/if}}.
+
+#### Key Files
+
+- **`index.html`** - The main HTML file that loads your app
+- **`src/index.{{ext}}`** - Entry point that bootstraps the application{{#if react}} and renders the React component tree{{/if}}
+- **`src/{{#if react}}App{{else}}app{{/if}}.{{ext}}`** - {{#if react}}Main React component that renders the {{#if (eq appType "todos")}}todo list{{else if (eq appType "chat")}}chat interface{{else if (eq appType "drawing")}}drawing
+    canvas{{else if (eq appType "game")}}game{{/if}}
+{{else}}Main application logic{{/if}}
+-
+**`src/{{#if react}}{{#if (eq appType "chat")}}ChatStore{{else if (eq appType "drawing")}}CanvasStore{{else}}Store{{/if}}{{else}}{{#if (eq appType "chat")}}chatStore{{else if (eq appType "drawing")}}canvasStore{{else}}store{{/if}}{{/if}}.{{ext}}`**
+- TinyBase {{#if (eq appType "chat")}}chat messages{{else if (eq appType "drawing")}}drawing canvas{{else}}main{{/if}} store configuration
+{{#if (eq appType "chat")}}
+  - **`src/{{#if react}}SettingsStore{{else}}settingsStore{{/if}}.{{ext}}`** - TinyBase settings store (not synchronized)
+{{/if}}
+{{#if (eq appType "drawing")}}
+  - **`src/{{#if react}}SettingsStore{{else}}settingsStore{{/if}}.{{ext}}`** - TinyBase settings store (not synchronized)
+{{/if}}
+- **`src/config.{{ext}}`** - Configuration settings{{#if server}} (including server connection URL){{/if}}
+
+#### How It Works
+
+The app uses **TinyBase** to manage application state in a reactive data store.
+{{#if schemas}}Type-safe schemas define the structure of your data, providing autocomplete
+  and compile-time type checking.{{/if}}
+
+{{#if sync}}
+  The store is a **MergeableStore**, which supports real-time synchronization across
+  multiple clients. When you open the app, it generates a unique room ID in the URL
+  path (e.g., `/abc123`). Anyone who visits the same URL will share the same data
+  and see live updates from other users.
+
+{{/if}}
+{{#if persistLocalStorage}}
+  **Persistence** is enabled using browser LocalStorage.
+  Your data is automatically saved and restored when you reload the page.
+
+{{/if}}
+{{#if persistSqlite}}
+  **Persistence** is enabled using SQLite WASM (running entirely in the browser).
+  Your data is automatically saved and restored when you reload the page.
+
+{{/if}}
+{{#if persistPglite}}
+  **Persistence** is enabled using PGlite (Postgres WASM running entirely in the browser).
+  Your data is automatically saved and restored when you reload the page.
+
+{{/if}}
+{{#if sync}}
+  **Synchronization** is powered by TinyBase's WebSocket synchronizer{{#if server}}, connecting
+    to your {{#if (eq syncType "durable-objects")}}Cloudflare Durable Objects{{else}}Node.js{{/if}} server{{else}} (connecting to a demo server at vite.tinybase.org){{/if}}.
+  When data changes locally, it's sent to the server and broadcast to all other
+  clients in the same room. The MergeableStore handles conflict resolution using
+  CRDTs, ensuring all clients converge to the same state.
+
+{{/if}}
+{{#if react}}
+  **React Integration** - TinyBase provides React hooks that automatically subscribe
+  to store changes and trigger re-renders when data updates. This means your UI
+  stays in sync with your data with minimal boilerplate.
+
+  Components like {{#if (eq appType "todos")}}`TodoList` and `TodoItem` use hooks like `useSortedRowIds`, `useRow`, and
+    callback hooks like `useAddRowCallback` and `useDelRowCallback`
+  {{else if (eq appType "chat")}}`MessageList` and `MessageInput` use TinyBase hooks to display and send messages
+  {{else if (eq appType "drawing")}}`Canvas` uses TinyBase hooks to track drawing state across users
+  {{else}}`Game` uses TinyBase hooks to manage game state{{/if}} to interact
+  with the store.
+
+{{/if}}
+{{#if server}}
+  ### Server
+
+  The `server` directory contains your {{#if (eq syncType "durable-objects")}}Cloudflare Durable Objects{{else}}Node.js{{/if}} WebSocket server.
+
+  #### Key Files
+
+  - **`index.{{ext}}`** - Server entry point
+
+  #### How It Works
+
+  {{#if (eq syncType "durable-objects")}}
+    The server uses **Cloudflare Durable Objects** to provide persistent, distributed
+    synchronization. Each room (identified by the URL path) maps to a Durable Object
+    instance that:
+
+    - Maintains the canonical state in SQL storage (using Durable Object SQL Storage)
+    - Handles WebSocket connections from clients
+    - Broadcasts changes to all connected clients in the room
+    - Automatically persists data, ensuring durability across deployments
+
+    The `TinyBaseDurableObject` class extends `WsServerDurableObject` and creates a
+    MergeableStore with a SQL storage persister. Cloudflare's infrastructure ensures
+    that all clients connecting to the same path are routed to the same Durable
+    Object instance.
+
+    To deploy to Cloudflare Workers, you'll need to configure your `wrangler.toml`
+    file with your Durable Object bindings.
+  {{else}}
+    The server runs a **Node.js WebSocket server** using the `ws` library. It acts
+    as a relay between clients, broadcasting state changes to all connected clients
+    in the same room.
+
+    When a client connects to a path (e.g., `/abc123`), the server groups them with
+    other clients on the same path and ensures all changes are synchronized.
+
+    The server logs when clients join or leave rooms, helping you monitor activity
+    during development.
+  {{/if}}
+
+{{/if}}
 ## Learn More
 
 - [TinyBase Documentation](https://tinybase.org)

package/templates/client/index.html.hbs

@@ -168,7 +168,11 @@
               A tic-tac-toe game demonstrating turn-based logic and computed game state.
             {{/if}}
             <br><br>
-            Built with {{#if typescript}}TypeScript{{#if schemas}} (using typed store schemas){{/if}}{{else}}JavaScript{{/if}}{{#if react}} and React{{/if}}.
+            Built with: {{#if typescript}}TypeScript{{#if schemas}} (using typed store schemas){{/if}}{{else}}JavaScript{{/if}}{{#if react}} and React{{/if}}.{{#if persist}}
+              <br><br>
+              Persistence: {{#if persistLocalStorage}}Local Storage{{else if persistSqlite}}SQLite{{else if persistPglite}}PGlite{{/if}}.{{/if}}{{#if sync}}
+              <br><br>
+              Sync: {{#if (eq syncType "remote")}}Remote{{else if (eq syncType "node")}}Node.js Server{{else if (eq syncType "durable-objects")}}Durable Objects{{/if}}.{{/if}}
           </div>
         </div>
       </div>

package/templates/server/index.ts.hbs

@@ -0,0 +1,43 @@
+{{#if isDurableObject}}
+  {{addImport "import {createMergeableStore} from 'tinybase';"}}
+  {{addImport "import {createDurableObjectSqlStoragePersister} from 'tinybase/persisters/persister-durable-object-sql-storage';"}}
+  {{addImport "import {getWsServerDurableObjectFetch, WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';"}}
+
+  export class TinyBaseDurableObject extends WsServerDurableObject {
+  createPersister() {
+  const store = createMergeableStore();
+  const persister = createDurableObjectSqlStoragePersister(
+  store,
+  this.ctx.storage.sql,
+  );
+  return persister;
+  }
+
+  onClientId(
+  pathId: string,
+  clientId: string,
+  addedOrRemoved: IdAddedOrRemoved,
+  ) {
+  console.log(
+  `Client ${clientId} ${addedOrRemoved == 1 ? 'joined' : 'left'} /${pathId}`,
+  );
+  }
+  }
+
+  export default {
+  fetch: getWsServerDurableObjectFetch('TinyBaseDurableObjects'),
+  };
+{{else}}
+  {{addImport "import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';"}}
+  {{addImport "import {WebSocketServer} from 'ws';"}}
+
+  const PORT = 8043;
+
+  const wsServer = createWsServer(new WebSocketServer({port: PORT}));
+
+  wsServer.addClientIdsListener(null, (wsServer, pathId, clientId, addedOrRemoved) => {
+  console.log(`Client ${clientId} ${addedOrRemoved == 1 ? 'joined' : 'left'} /${pathId}`);
+  });
+
+  console.log(`WebSocket server running on ws://localhost:${PORT}`);
+{{/if}}

package/templates/server/package.json.hbs

@@ -5,12 +5,11 @@
 "main": "index.ts",
 "scripts": {
 {{#list}}
+  {{includeFile template="server/index.ts.hbs" output="server/index.ts"}}
   {{#if (eq serverType "node")}}
-    {{includeFile template="server/index-node.ts.hbs" output="server/index.ts"}}
     "dev": "tsx watch index.ts"
     "start": "node index.js"
   {{else}}
-    {{includeFile template="server/index-do.ts.hbs" output="server/index.ts"}}
     {{includeFile template="server/wrangler.toml.hbs" output="server/wrangler.toml"}}
     {{#if typescript}}
       {{includeFile template="server/tsconfig.json.hbs" output="server/tsconfig.json"}}

package/templates/server/index-do.ts.hbs

@@ -1,18 +0,0 @@
-{{addImport "import {createMergeableStore} from 'tinybase';"}}
-{{addImport "import {createDurableObjectSqlStoragePersister} from 'tinybase/persisters/persister-durable-object-sql-storage';"}}
-{{addImport "import {getWsServerDurableObjectFetch, WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';"}}
-
-export class TinyBaseDurableObject extends WsServerDurableObject {
-createPersister() {
-const store = createMergeableStore();
-const persister = createDurableObjectSqlStoragePersister(
-store,
-this.ctx.storage.sql,
-);
-return persister;
-}
-}
-
-export default {
-fetch: getWsServerDurableObjectFetch('TinyBaseDurableObjects'),
-};

package/templates/server/index-node.ts.hbs

@@ -1,8 +0,0 @@
-{{addImport "import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';"}}
-{{addImport "import {WebSocketServer} from 'ws';"}}
-
-const PORT = 8043;
-
-const wsServer = createWsServer(new WebSocketServer({port: PORT}));
-
-console.log(`WebSocket server running on ws://localhost:${PORT}`);