{"id":20426295,"url":"https://github.com/marchantweb/usepartyref","last_synced_at":"2025-08-21T06:30:58.515Z","repository":{"id":246770746,"uuid":"821910761","full_name":"marchantweb/usePartyRef","owner":"marchantweb","description":"A Vue 3 ref that syncs in real-time with other clients using PartyKit 🎈","archived":false,"fork":false,"pushed_at":"2024-09-15T14:08:55.000Z","size":1557,"stargazers_count":37,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-16T09:14:42.763Z","etag":null,"topics":["partykit","realtime","signals","vue"],"latest_commit_sha":null,"homepage":"https://usepartyref.pages.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marchantweb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-29T19:45:29.000Z","updated_at":"2024-12-05T05:02:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"106b2928-934b-4292-bd69-ebe2c4ed72f2","html_url":"https://github.com/marchantweb/usePartyRef","commit_stats":null,"previous_names":["marchantweb/usepartyref"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marchantweb%2FusePartyRef","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marchantweb%2FusePartyRef/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marchantweb%2FusePartyRef/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marchantweb%2FusePartyRef/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marchantweb","download_url":"https://codeload.github.com/marchantweb/usePartyRef/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230494921,"owners_count":18235046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["partykit","realtime","signals","vue"],"created_at":"2024-11-15T07:16:09.394Z","updated_at":"2024-12-19T20:08:21.102Z","avatar_url":"https://github.com/marchantweb.png","language":"TypeScript","readme":"# usePartyRef\n\n![usePartyRef](https://github.com/marchantweb/usePartyRef/raw/main/cover.jpg)\n\n`usePartyRef()` is a Vue 3 composable that extends the functionality of the standard `ref()` to enable real-time,\nsynchronized state across multiple clients globally.\n\nIt transforms local reactive state into a shared state across all connected clients, allowing you to\nbuild multiplayer interactive experiences using the Vue lifecycle hooks you're familiar with. The composable returns a `Ref`, so you\ncan `watch` it, bind it to inputs, run a `computed` on it, etc.\n\nUnder the hood, it's using [PartyKit](https://www.partykit.io/) stateful servers and websockets, based\non [CloudFlare Durable Objects](https://developers.cloudflare.com/durable-objects/), to keep values in sync and persist them beyond the life of the browser window. The library is written in TypeScript and is fully type-safe.\n\n## 📦 Installation\n\nInstall `usePartyRef` via npm by running:\n\n```bash\nnpm install usepartyref\n```\n\n---\n\n## 🚀 Usage\n\nBelow is a comparison of using Vue's native `ref()` versus `usePartyRef()` to illustrate how you can seamlessly use\nglobally shared state as easily as using a normal ref:\n\n```ts\n// Use Vue's native ref() for local state\nconst count: Ref\u003cnumber\u003e = ref(0)\n\n// Use usePartyRef() for shared state\nconst sharedCount: Ref\u003cnumber\u003e = usePartyRef({\n    namespace: 'my-project', // Choose something unique\n    key: \"count\",\n    defaultValue: 0\n})\n\n// Computed, watch, and other reactive utilities work just like a normal ref\nconst doubled = computed(() =\u003e sharedCount.value * 2)\n```\n\nWith `usePartyRef()`, the count state is synchronized in real time across all clients that subscribe to it. That might\nbe two browser tabs on your local machine, or thousands of users all over the world.\n\n### Ready State\n\nA special note here is that the ref returned by `usePartyRef` is actually a `PartyRef` type. This type extends `Ref` adding a `ready` property that is a `Ref\u003cboolean\u003e`. This property is `true` when the connection is established and the value is ready to be used, and `false` when the connection closes.\n\nYou can watch this property to know when the value is ready to be used:\n\n```ts\n// If you need to know when the connection is established\nconst isReady: ComputedRef\u003cboolean\u003e = computed(() =\u003e sharedCount.ready.value)\n````\n\nNote that trying to access this property in a template will fail, as Vue automatically unwraps the value - so instead use a computed variable such as `isReady` above.\n\n---\n\n## 🎈 Managed vs. Self-Hosting\n\n`usePartyRef` is built on top of [PartyKit](https://www.partykit.io/), a managed service that handles the real-time\nsynchronization of state across clients. This means you don't need to worry about setting up your own server or managing\nthe infrastructure.\n\nBy default, `usePartyRef` uses the PartyKit server hosted on the package author's account that requires no setup on your part. This is great for getting started quickly and for small projects, but it's not recommended for production use. Under heavy traffic it may be rate limited, and there's a greater chance of namespace conflicts with other users.\n\n### Self-host on your own PartyKit account:\n\n1. Fork this repo\n2. Run `server:deploy` and follow the prompts to authenticate with your own GitHub account to PartyKit\n3. Configuring the `usePartyRef` composable to point at your own account by setting the `host` option:\n\n```ts\nconst count: Ref\u003cnumber\u003e = usePartyRef({\n    namespace: 'my-project',\n    key: \"count\",\n    defaultValue: 0,\n    host: '[projectname].[username].partykit.dev' // server:deploy will give you this URL\n})\n```\nForking it and hosting on your own account also has the benefit of providing a level of privacy and control over your data. You can modify the PartySocket connection and the server to use your own authentication approaches along with any business logic you need - although at that point you may want to consider using PartyKit directly.\n\nYou can also go as far as actually **self-hosting on CloudFlare**. For that, see\nthe [PartyKit documentation](https://docs.partykit.io/guides/deploy-to-cloudflare/).\n\n---\n\n## What about Y-PartyKit / Yjs?\n\n[Y-PartyKit](https://docs.partykit.io/reference/y-partykit-api/) is a similar project that uses [Yjs](https://yjs.dev/) for real-time collaboration around shared data types. Both `usePartyRef` and `Y-PartyKit` are built on top of PartyKit, but they have different use cases and levels of involvement/complexity.\n\n`usePartyRef` is designed to be a drop-in replacement for Vue's `ref()` that allows you to share reactive state across clients. It's a simple, high-level API that removes the need for you to worry about the underlying data structures and synchronization logic. It just works out of the box with no setup required.\n\n`Y-PartyKit` is a more complex, lower-level API that allows you to share any data type across clients. It's built on top of Yjs, which is a CRDT library that allows for more complex data structures like maps, arrays, and text. It's great for more complex data structures and collaborative editing.\n\nIf you're looking for a simple way to share reactive state across clients, `usePartyRef` is the way to go. If you need more complex data structures or collaborative editing, `Y-PartyKit` might be a better fit.\n\n---\n\n## 📚 Contributions\n\nContributions are welcome! Feel free to open an issue or submit a pull request if you have any ideas or improvements.\n\n---\n\n## 🔗 Links\n\n- [PartyKit](https://partykit.io/)\n- [Follow on Twitter](https://twitter.com/marchantweb)\n- [Chat on Discord](https://discordapp.com/users/1165287468568944640)\n\n---\n\n## 📄 License\n\nCopyright (c) 2024 Simon Le Marchant _(Marchant Web, LLC.)_\n\n`usePartyRef` is licensed under the [MIT License](https://github.com/vuexyz/vuexyz/blob/main/LICENSE). Licensed works,\nmodifications, and larger works may be distributed under different terms and without source code.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarchantweb%2Fusepartyref","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarchantweb%2Fusepartyref","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarchantweb%2Fusepartyref/lists"}