--- title: Radicle repos and issues description: Build a code-collaboration dapp on Radicle in Freedom: read repositories with rad: URLs, get a repository onto the user's node, and write issues and comments with window.radicle. kick: Radicle dek: Read public repositories with fetch('rad:…'), ask the user's node to seed what it does not have, and write issues and comments as the user. --- A Freedom page can be a full forge client without a server. Canopy, a GitHub-style forge served from Swarm, works exactly this way. ## Read with rad: URLs Reads are plain `fetch()` calls against the user's own node, with no prompt and no connection: ```javascript const rid = 'z…'; // the bare repository id const res = await fetch(`rad:${rid}`); if (res.status === 404) { // the node does not have it (yet): see the next section } const repo = await res.json(); const head = repo.payloads['xyz.radicle.project'].meta.head; const issues = await (await fetch(`rad:${rid}/issues?status=open&perPage=50`)).json(); ``` Revisions must be full 40-character SHAs, so start from the metadata's `head`. Routes, pagination and error bodies are in [rad: URLs](rad-urls.html.md). ## Get a repository onto the node `rad:` only serves what the node stores. To open a repository the node does not have, ask the user to seed it and wait for the fetch: ```javascript const fullRid = `rad:${rid}`; function fetched() { return new Promise((resolve, reject) => { const onStatus = (s) => { if (s.rid !== fullRid) return; if (s.state === 'fetched') { done(); resolve(s); } }; const done = () => window.radicle.removeListener('seedStatus', onStatus); window.radicle.on('seedStatus', onStatus); }); } await window.radicle.requestAccess(); // prompts once per origin const waiting = fetched(); // listen before seeding const { status } = await window.radicle.seed({ rid: fullRid }); // prompts for this repo if (status.state !== 'fetched') await waiting; ``` Things to know: - `seed` resolves as soon as the policy is written; the fetch runs in the background. Show `progress.phase` (`resolving`, `connecting`, `fetching`, …) so the user sees it moving; there are no percentages. - A `failed` state is not final: the node keeps retrying, and you can call `sync({ rid })` to restart the fetch without another prompt. A real app should also give up waiting after a while and say so. - After a reload, `getSeedStatus({ rid })` returns the latest snapshot. - `seed` and `unseed` prompt every time, per repository. ## Write issues and comments Writes are signed with the user's Radicle node identity, the same author everywhere, after a one-time signing grant: ```javascript const me = await window.radicle.getIdentity(); // asks for the signing grant const { id } = await window.radicle.createIssue({ rid: fullRid, title: 'Crash when opening settings', description: 'Steps to reproduce: …', labels: ['bug'], }); await window.radicle.commentIssue({ rid: fullRid, issueId: id, body: 'Also on Linux.' }); await window.radicle.editIssueState({ rid: fullRid, issueId: id, state: 'closed' }); ``` Each write goes into the node's own storage, the same storage `rad:` reads from, and is announced to the network before the call resolves. A write that timed out may still have landed, so read before you retry rather than posting twice. Limits and input rules (title 200 bytes, body 64 KiB, up to 10 labels) are in the [reference](radicle.html.md#input-rules). Patches can be commented on but not created from a page in this version; see [Not in this version](radicle.html.md#not-in-this-version). ## Test against a real repository Freedom Browser's own Radicle mirror, `rad:z3QXuMvMmSeEX3ZgoUidZC1v5MkKE`, is public and fine for read tests. Do not create test issues on someone else's repository: initialise your own with the Radicle CLI and use that.