deprecate useBootstrap

automerge · Apr 4, 2024 · 84f0a2e · 84f0a2e
1 parent f541499
commit 84f0a2e
Show file tree

Hide file tree

Showing 3 changed files with 14 additions and 129 deletions.
diff --git a/packages/automerge-repo-react-hooks/README.md b/packages/automerge-repo-react-hooks/README.md
@@ -2,11 +2,6 @@
 
 These hooks are provided as helpers for using Automerge in your React project.
 
-#### [useBootstrap](./src/useBootstrap.ts)
-
-This hook is used to load a document based on the URL hash, for example `//myapp/#documentId=[document ID]`.
-It can also load the document ID from localStorage, or create a new document if none is specified.
-
 #### [useLocalAwareness](./src/useLocalAwareness.ts) & [useRemoteAwareness](./src/useRemoteAwareness.ts)
 
 These hooks implement ephemeral awareness/presence, similar to [Yjs Awareness](https://docs.yjs.dev/getting-started/adding-awareness).
@@ -28,58 +23,3 @@ Return a document & updater fn, by ID.
 
 Return a handle, by ID.
 
-## Example usage
-
-### App Setup
-
-```ts
-import React, { StrictMode } from "react"
-import ReactDOM from "react-dom/client"
-
-import { Repo, DocCollection } from "@automerge/automerge-repo"
-
-import { BroadcastChannelNetworkAdapter } from "@automerge/automerge-repo-network-broadcastchannel"
-
-import App, { RootDocument } from "./App.js"
-import { RepoContext } from "@automerge/automerge-repo-react-hooks"
-
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const sharedWorker = new SharedWorker(
-  new URL("./shared-worker.js", import.meta.url),
-  { type: "module", name: "@automerge/automerge-repo-shared-worker" }
-)
-
-async function getRepo(): Promise<DocCollection> {
-  return await Repo({
-    network: [new BroadcastChannelNetworkAdapter()],
-    sharePolicy: peerId => peerId.includes("shared-worker"),
-  })
-}
-
-const initFunction = (d: RootDocument) => {
-  d.items = []
-}
-
-const queryString = window.location.search // Returns:'?q=123'
-
-// Further parsing:
-const params = new URLSearchParams(queryString)
-const hostname = params.get("host") || "automerge-storage-demo.glitch.me"
-
-getRepo().then(repo => {
-  useBootstrap(repo, initFunction).then(rootDoc => {
-    const rootElem = document.getElementById("root")
-    if (!rootElem) {
-      throw new Error("The 'root' element wasn't found in the host HTML doc.")
-    }
-    const root = ReactDOM.createRoot(rootElem)
-    root.render(
-      <StrictMode>
-        <RepoContext.Provider value={repo}>
-          <App rootDocumentId={rootDoc.documentId} />
-        </RepoContext.Provider>
-      </StrictMode>
-    )
-  })
-})
-```
diff --git a/packages/automerge-repo-react-hooks/src/index.ts b/packages/automerge-repo-react-hooks/src/index.ts
@@ -5,84 +5,23 @@
  *
  * These hooks are provided as helpers for using Automerge in your React project.
  *
- * #### {@link useBootstrap}
- * This hook is used to load a document based on the URL hash, for example `//myapp/#documentId=[document ID]`.
- * It can also load the document ID from localStorage, or create a new document if none is specified.
- *
- * #### {@link useLocalAwareness} & {@link useRemoteAwareness}
- * These hooks implement ephemeral awareness/presence, similar to [Yjs Awareness](https://docs.yjs.dev/getting-started/adding-awareness).
- * They allow temporary state to be shared, such as cursor positions or peer online/offline status.
- *
- * Ephemeral messages are replicated between peers, but not saved to the Automerge doc, and are used for temporary updates that will be discarded.
- *
  * #### {@link useRepo}/{@link RepoContext}
  * Use RepoContext to set up react context for an Automerge repo.
  * Use useRepo to lookup the repo from context.
  * Most hooks depend on RepoContext being available.
  *
- * #### {@link useDocument }
- * Return a document & updater fn, by ID.
- *
- * #### {@link useHandle }
- * Return a handle, by ID.
- *
- * ## Example usage
- *
- * ### App Setup
+ * #### {@link useDocument}
+ * Return the current state of a document (or undefined) and a change function.
  *
- * ```ts
- * import React, { StrictMode } from "react"
- * import ReactDOM from "react-dom/client"
+ * #### {@link useHandle}
+ * Return a DocHandle by passing in a DocumentURL.
  *
- * import { Repo, DocCollection } from "@automerge/automerge-repo"
- *
- * import { BroadcastChannelNetworkAdapter } from "@automerge/automerge-repo-network-broadcastchannel"
- *
- * import App, { RootDocument } from "./App.js"
- * import { RepoContext } from "@automerge/automerge-repo-react-hooks"
- *
- * // eslint-disable-next-line @typescript-eslint/no-unused-vars
- * const sharedWorker = new SharedWorker(
- *   new URL("./shared-worker.js", import.meta.url),
- *   { type: "module", name: "@automerge/automerge-repo-shared-worker" }
- * )
- *
- * async function getRepo(): Promise<DocCollection> {
- *   return await Repo({
- *     network: [
- *       new BroadcastChannelNetworkAdapter(),
- *     ],
- *     sharePolicy: peerId => peerId.includes("shared-worker"),
- *   })
- * }
- *
- * const initFunction = (d: RootDocument) => {
- *   d.items = []
- * }
- *
- * const queryString = window.location.search // Returns:'?q=123'
+ * #### {@link useLocalAwareness} & {@link useRemoteAwareness}
+ * These hooks implement ephemeral awareness/presence, similar to [Yjs Awareness](https://docs.yjs.dev/getting-started/adding-awareness).
+ * They allow temporary state to be shared, such as cursor positions or peer online/offline status.
  *
- * // Further parsing:
- * const params = new URLSearchParams(queryString)
- * const hostname = params.get("host") || "automerge-storage-demo.glitch.me"
+ * Ephemeral messages are replicated between peers, but not saved to the Automerge doc, and are used for temporary updates that will be discarded.
  *
- * getRepo().then(repo => {
- *   useBootstrap(repo, initFunction).then(rootDoc => {
- *     const rootElem = document.getElementById("root")
- *     if (!rootElem) {
- *       throw new Error("The 'root' element wasn't found in the host HTML doc.")
- *     }
- *     const root = ReactDOM.createRoot(rootElem)
- *     root.render(
- *       <StrictMode>
- *         <RepoContext.Provider value={repo}>
- *           <App rootDocumentId={rootDoc.documentId} />
- *         </RepoContext.Provider>
- *       </StrictMode>
- *     )
- *   })
- * })
- * ```
  */
 export { useDocument } from "./useDocument.js"
 export { useDocuments } from "./useDocuments.js"

diff --git a/packages/automerge-repo-react-hooks/src/useBootstrap.ts b/packages/automerge-repo-react-hooks/src/useBootstrap.ts
@@ -1,3 +1,8 @@
+/** Deprecated as of 1.1.6
+ * scheduled removal in 2.0 (if it's 2.0 or great, get it out of here)
+ * but you probably aren't using it anyway
+ */
+
 import { DocHandle, Repo, type AutomergeUrl } from "@automerge/automerge-repo"
 import { useEffect, useState, useMemo } from "react"
 import { useRepo } from "./useRepo.js"
@@ -62,6 +67,7 @@ export interface UseBootstrapOptions<T> {
 }
 
 /**
+ * @deprecated Use the simpler example code in the README instead. 
  * This hook is used to set up a single document as the base of an app session.
  * This is a common pattern for simple multiplayer apps with shareable URLs.
  *