DEV Community

Cover image for Writing the contributor guide an open-source project didn't have, with Thally
Adetayo Lasisi
Adetayo Lasisi

Posted on Edited on

Writing the contributor guide an open-source project didn't have, with Thally

Svelte Bits is a library of 164 animated Svelte components, ported one at a time from React Bits. I've ported four of them myself, three of which are merged. The project's README gives contributors exactly two sentences of guidance, yet my smallest port still touched five files.

So I wrote the guide I wish I'd had, and published it with Thally. This article shows how to do the same for any project: set up a Thally site, configure it, write the content, and publish it, including the problems I hit along the way.

What you'll need

  • Node.js 20 or later (I used 22)
  • A GitHub account
  • A free Thally Cloud account
  • A project you know well enough to explain to a newcomer

1. Create the site

Sign up at app.thally.io. After you verify your email, a short onboarding asks for your company or project name, your role and team size, then your main docs goal, such as launching new documentation or keeping docs aligned with product changes. The answers only tailor the setup guidance; they don't limit what you can do and how you use Thally.

From the dashboard, click Create a site. Setup has five steps.

Site details - This requires a name for the site, a one-line summary (what the product does and who the docs are for), and a .thally.app address of your choice. The free plan includes three sites. I used "Svelte Bits Contribution" as the name and sveltebits.thally.app as the address.

Docs source - You are given a handful of options to choose from, with Create a new docs repository being the recommended option. Thally first checks whether its GitHub App is installed, and offers to install it if it isn't. Thally creates the repo from its template and handles the first deployment. The repository is private by default; turn that off if you want readers to see the source.

Product sources - This step sets up Track, Thally's feature that reads merged pull requests in your product repositories and works out what each one means for your docs. This is suitable for organisation repos. The contributor guide doesn't need it, so I clicked Skip for now.

Knowledge surfaces - Other places that describe the product, such as a website or help center, where Thally can propose updates. I skipped this too.

Review and publish - This is the final step; after you are satisfied with the details, you can confirm, and Thally publishes the starter site.

Dashboard after publishing

Now clone the new repository and run it locally:

git clone https://github.com/<you>/<your-docs-repo>.git
cd <your-docs-repo>
npm install
npm run dev
Enter fullscreen mode Exit fullscreen mode

The site runs at http://localhost:3040.

2. Clear out the starter

The starter is a complete Next.js app with example content for every feature: an API reference generated from openapi.yaml, a changelog, component showcases and guides. That's useful for exploring, but a three-page guide doesn't need most of it. I deleted:

  • src/content/components.mdx, src/content/customization.mdx and the example guides
  • src/content/api/ and openapi.yaml
  • src/content/changelog.mdx

Delete openapi.yaml too, not just the API pages. Otherwise, the file is still served publicly.

3. Configure the site

Two files control most of it.

src/data/site.ts holds the site name, description and header links:

export const siteConfig: SiteConfig = {
  name: 'Svelte Bits Contributors',
  description: 'An unofficial guide to porting React Bits components to Svelte Bits.',
  repoUrl: 'https://github.com/<you>/<your-docs-repo>',
  links: [
    { label: 'Svelte Bits', href: 'https://github.com/DavidHDev/svelte-bits' },
    { label: 'React Bits', href: 'https://github.com/DavidHDev/react-bits' },
  ],
  // brand settings unchanged
}
Enter fullscreen mode Exit fullscreen mode

Two things to know here. Thally adds "Docs" after the name in the header, so I avoided names ending in "Guide" or "Docs". And repoUrl powers the "Edit this page" link on every page, so point it at your docs repository, not the project you're documenting.

docs.json holds the navigation:

"tabs": [
  {
    "tab": "Guide",
    "groups": [
      { "group": "Get started", "pages": ["introduction", "quickstart"] },
      { "group": "Contributing", "pages": ["guides/port-a-component"] }
    ]
  }
]
Enter fullscreen mode Exit fullscreen mode

Each page name maps to an .mdx file in src/content/.

4. Write the content

I planned three pages, each answering one question:

  1. Introduction: What is Svelte Bits, and is contributing for me?
  2. Quickstart: Can I get it running on my machine?
  3. Guide: How do I port a component, from start to merged?

Before writing anything, I went back to the components I'd already ported. In my Svelte Bits clone, I ran git log --stat on each of my port commits, which lists every file a commit changed. Every port touched the same handful of files: the component itself, its demo page, and two config files that register it. That list became the table at the top of the porting guide, so a new contributor knows the whole job before they start.

The list also showed something odd: some of my PRs included a static/r/<name>.json file, and others didn't. When I checked the build setup, it turned out the file is generated automatically while the dev server runs. So the guide tells contributors not to write it by hand.

Thally pages are written in MDX, which is Markdown plus a few built-in components. These are the ones I used:

  • <Steps> for anything done in order. Each step ends with a way to check it worked.
  • <Tabs> for React and Svelte code side by side, which is the heart of a porting guide.
  • <AccordionGroup> for troubleshooting, so error messages stay scannable without filling the page.
  • <Warning> and <Note> for things that would otherwise make readers think something is broken.

5. Check and publish

Thally's checker catches broken links, frontmatter problems and pages missing from navigation:

npx --yes @thallylabs/cli@latest check
Enter fullscreen mode Exit fullscreen mode

Then preview locally, commit, and push to main. Thally deploys automatically.

Obstacles, and how I resolved them

  1. A wall of red errors on a fresh clone - Running Svelte Bits' npm run dev for the first time prints a long list of ENOENT … [plugin vite:dep-scan] errors. They look fatal, but the site works fine: Vite's dependency scanner mistakes the example code on demo pages for real imports. I put a warning right in the quickstart step, because this is exactly where a new contributor would give up.

  2. The original had moved on - React Bits rewrote Cursor Grid with WebGL in October, months after it was ported to Svelte. Nothing in either repo flags that. The guide now tells contributors to check the original's git history before and after porting, and to name the commit they ported from.

  3. My edits wouldn't show up - Saving a page did nothing in the browser, and even a manual refresh showed the old text. Only restarting the dev server worked. This one took real digging, so it gets its own section below.

  4. Pages missing from the sidebar are still live. - Before I cleaned up, the starter had eight example pages that weren't listed in docs.json. I assumed that meant they were hidden. They weren't; Thally still serves every .mdx file in src/content/ at its URL and includes it in search, llms.txt and the sitemap. If you don't want a page published, delete it or mark it hidden: true. Leaving it out of the navigation isn't enough.

Deep dive: why my edits wouldn't show up

Halfway through writing the guide, my feedback loop broke. I'd save quickstart.mdx, switch to the browser, and see the old text. Refreshing didn't help. The only thing that worked was stopping npm run dev and starting it again, every time.

Oddly, it only affected content. Edit a .tsx component and the page hot-reloaded as it should. When I edited an .mdx page, nothing happened.

What was actually going on

Two separate problems were stacked on top of each other.

The server remembered the first version of every page, In development, the starter is meant to compile each page fresh from disk on every request. The code even says so in a comment: Development always compiles for fresh authoring feedback. But that fresh compile sits behind a cache. The first time you open a page, getDocFromParams() in src/data/get-doc.ts stores the result in a plain Map, and nothing ever removes it. Simplified, it looks like this:

const dynamicDocCache = new Map()

export async function getDocFromParams(slug) {
  let pending = dynamicDocCache.get(slug)
  if (!pending) {
    pending = loadDocFromSource(slug) // reads and compiles the .mdx
    dynamicDocCache.set(slug, pending) // ...and keeps it forever
  }
  return pending
}
Enter fullscreen mode Exit fullscreen mode

Page titles, descriptions and the sidebar have the same kind of cache in src/data/docs.ts. So the fresh compile ran exactly once per page, and every request after that got the stored copy. That's why refreshing the browser didn't help: the browser was asking for a new copy, but the server kept handing over the old one.

In production, this cache makes perfect sense, because content doesn't change while the server is running. In development it's the opposite of what you want.

Nothing told the browser a file had changed. Next.js hot reload follows your imports. When you save a component, Next.js knows which pages import it and updates them. Thally's MDX pages aren't imported. They're read from disk when a request comes in, so as far as Next.js is concerned, saving one doesn't affect anything.

Fixing just one of these doesn't help much. Clear the cache without a reload signal, and you still have to refresh by hand. Send a reload signal without clearing the cache, and the browser refreshes straight back into the old content. It needed both.

Why I couldn't just fix the file

The obvious move is to edit get-doc.ts. But the Thally starter splits its files into two kinds. Your content and site settings belong to you. The framework code, including get-doc.ts and docs.ts, is a generated copy of Thally's runtime, listed in starter-release.json. The repository's own instructions say never to hand-edit those files. The fixes belong in Thally's runtime repository and arrive through an update. Any local edit gets overwritten the next time you run npm run starter:update.

So the real fix belongs upstream. But I had a guide to finish, so I wrote a small development-only patch that I keep on my machine and never commit.

The fix

The patch has three parts.

  1. Notice when content changes - A new helper, src/lib/dev-content-revision.ts, keeps a counter. It walks src/content/, builds a fingerprint from each file's path, modification time and size, and bumps the counter whenever the fingerprint changes. It checks at most once every 100 milliseconds so a busy page doesn't rescan the folder dozens of times, and it always returns 0 outside development.

I used a counter rather than switching the caches off. The caches still do their job between edits, so pages aren't recompiled on every request, and the cache code doesn't need to know anything about files on disk. It only has to notice when one number changes.

  1. Clear the caches when the counter moves - In get-doc.ts and docs.ts, a few lines compare the counter with the last value they saw. If it has changed, they empty their caches before doing anything else:
const devRevision = getDevContentRevision()
if (devRevision !== observedDevContentRevision) {
  observedDevContentRevision = devRevision
  dynamicDocCache.clear()
}
Enter fullscreen mode Exit fullscreen mode

With just this, a manual refresh shows your latest text.

  1. Tell the browser - A development-only route, /api/dev-content-events, watches src/content/ with Node's fs.watch and sends a message to the browser whenever a file changes. It waits 150 milliseconds after the last change, so an editor that writes a file in several steps triggers one refresh, not three. On the page, a tiny client component listens for that message and calls router.refresh().

I picked server-sent events because the messages only ever go one way, from server to browser. Browsers support them natively through EventSource, so there's no extra package or WebSocket server to run. And I used router.refresh() instead of reloading the whole page because it re-renders the content in place and keeps your scroll position. That matters a lot when you're checking a paragraph halfway down a long guide.

Every piece checks NODE_ENV, so production behaves exactly as before. To test it, I created a throwaway page containing VERSION_ONE and loaded it, then changed the text to VERSION_TWO and loaded it again. The second request returned VERSION_TWO with no restart, and the browser refreshed on its own the moment I saved.

The alternatives

Option Good Bad
Restart the dev server after every edit No code changes, no risk Slow, and it breaks your writing flow
Turn the caches off in development Simpler than a counter Recompiles every page on every request, and you still need a reload signal
Have the browser poll for changes No streaming connection Constant requests and slower updates
Reload the whole page instead of router.refresh() One line of code Loses scroll position and any page state
Fix it in Thally's runtime The real fix, for every Thally site Needs review and a release before it reaches you
Local patch (what I did) Works immediately Must never be committed, and updates overwrite it

The catch

A local patch to framework files is a stopgap. I keep it out of every commit by staging only docs.json and src/content/, and I'll lose it the next time I update the starter.

Wrapping up

When I started, the Svelte Bits README gave contributors two sentences. Now there's a three-page guide that takes someone from cloning the project to a merged port: what to expect, how to get it running, and every file a port touches.

Most of what went into the guide didn't come from memory. It came from looking back at my own pull requests and from following every step on a fresh clone. That testing is what turned up the wall of harmless errors, the Cursor Grid rewrite and the generated registry files. The same habit carried over to Thally itself. When my edits stopped showing up, I read the starter's code instead of guessing, and found the cause in a few lines of caching.

What's next

Report the dev-server caching issue to Thally, along with the patch, so the fix can land in the runtime for every site instead of living only on my machine.

If your project's contributing section is only a couple of sentences long, you probably already know enough to fix it. Start with your own git history.

Read the guide: sveltebits.thally.app
Source: github.com/adetyaz/svelte-bits-contribution

Top comments (4)

Collapse
 
docsalive profile image
DocsAlive Team •

For the porting guide, consider a small fixture component in a clean clone and a CI smoke test that follows the documented setup and checks the generated registry entry. Keep the human review of animation and behavior, but automate the steps that can silently drift. Your note about naming the upstream commit is especially useful: recording it alongside the port gives maintainers a concrete starting point when React Bits changes, instead of having to reconstruct which version the Svelte implementation followed.

Collapse
 
babalasisi profile image
Adetayo Lasisi •

Noted

Collapse
 
mayur_gadakh profile image
Mayur Gadakh •

the table of every file a port touches is the useful part, thats the thing new contributors alwyas guess wrong. the cursor grid rewrite outdating one port makes me wonder how you notice when upstream changes make a guide page wrong, is it just someone reading the diff. im building docup for that kind of drift, it turns a github repo into a docs site that updates as the code changes

Collapse
 
babalasisi profile image
Adetayo Lasisi •

I will, first of all, say I was already in contact with the creator of ReactBits, and I saw these changes happen; that being said. I like to believe everyone who contributes pulls from the upstream, either when they are about to port or when they need to push their changes. I tend to look out for changes personally, and with the help of coding assistants, I ask what changes have been made since the last time I ported (i.e new components or a change in old components).

Also, Thally does something very similar; during the process of creating the docs site, you can also add the repos for Thally to take notice of; it's one of the different use cases for Thally