HelioKit

One repository, two artifacts

The same repository produces a published CLI and a documentation website, and the two builds are kept apart on purpose. The CLI is bundled by tsup into an ESM file that the package manifest points its binary at. The site is built by Vite into a separate directory so it can never collide with the CLI bundle sitting next to it.

This arrangement is what makes the copy-in model work at all. The components live in the repository as ordinary source files, the site imports them directly to render live previews, and the published package carries those same files so the CLI has something to copy. There is no build step that turns a component into a distributable, because a component never becomes one.

What the CLI does

Five commands, built on Commander. Two of them list what is available, one sets a project up, one adds components, and one adds a full page template.

Adding a component is deliberately unclever: work out the destination directory, then copy the component's folder there. Components are self-contained, so there is no dependency graph to walk and nothing to rewrite on the way in. A slug that does not exist prints an error and the run continues with the rest rather than aborting the batch.

Deciding where files go, once

The tool does not try to infer the whole shape of an unfamiliar repository. It asks: Vite, Next.js, or a custom path. Guessing wrong here is not cosmetic, since it means files land in a directory the project does not use, with imports that never resolve, so the question is asked outright rather than answered by heuristics.

There is exactly one inference. On Next.js it checks whether a source directory exists and picks the nested or root component path accordingly, printing a warning when it falls back to the root.

The answer is then offered up for saving into a small config file at the project root. Every later command reads that file and skips the prompt entirely, so the interrogation happens once per project rather than once per component.

The setup command

Components assume Tailwind v4, framer-motion and lucide-react. Rather than documenting that and hoping, there is a command that installs them, with the Tailwind integration package chosen by framework: the Vite plugin for Vite, the PostCSS plugin plus PostCSS itself for Next.

It then wires the build. On Vite it reads the config, prepends the plugin import and injects the call into the plugins array, but only when the plugin is not already referenced, so re-running it does not stack duplicates. On Next it writes a PostCSS config when one is missing.

Finally it makes sure the Tailwind import is present in the stylesheet entry, creating that file if it does not exist, appending the line if the file exists without it, and saying so and doing nothing if it is already there. Each of the three outcomes prints a different message, because a setup step that is silent about what it changed in someone else's repository is worse than one that does nothing.

Templates, and the one place dependencies are tracked

Beyond single components there are full page templates. A manifest maps each template name to its source file and to the list of component slugs that page imports.

Copying a template therefore copies the page and then the components it needs, so the result compiles without a second command and without the user having to read the imports to find out what is missing. This manifest is the only place in the project where one thing declares that it depends on another, and it exists precisely because a template is the only thing here that is not self-contained.

Components that stay portable

Two dozen components live in the repository, each in its own folder with a demo file beside it that the documentation preview renders.

Portability is a constraint, not an aspiration. Beyond React the only imports permitted are framer-motion and lucide-react, and colours come from theme tokens rather than literals, which is what allows a component to be dropped into a repository nobody planned for and still look correct. The heavier visual pieces skip the motion library entirely and drive a canvas from a requestAnimationFrame loop with typed, documented props for the things worth tuning.

Two themes from three variables

The whole design system is three colour tokens and a handful of font tokens declared in the Tailwind v4 theme block. Light mode is a single class that redefines those three colours. There is no dark variant anywhere in any component, because a component that reads a background token is already correct in both themes and one that hardcodes a colour cannot be fixed by adding variants to it.

The background colour is also painted on the document itself rather than only on component wrappers. Anything the application has not painted yet, an overscroll bounce or a gap while a lazy route loads, shows the browser canvas underneath, and that canvas is white unless the document says otherwise.

The documentation site

Every component has a data module holding its live preview, its source, its installation steps and its props table. A slug map turns those into dynamic imports, so opening one component's page loads that component's payload and nothing else. A small Redux slice holds whichever component is currently being viewed and backs the preview, the code panel and the props table from one place.

The manual install snippet is not a copy of the component pasted into a string. It imports the component file raw, so the code shown on the page is the file on disk. Documentation that is a transcription of the source drifts from it the first time the source changes; documentation that is the source cannot.

Prerendering, and what is deliberately not prerendered

The site is prerendered to static HTML, and the routes are lazily loaded per page so the initial download does not carry the syntax highlighter, the motion library and every canvas component along with the landing page.

Only the static routes are emitted as HTML. The parameterised ones, individual component pages and template previews, stay client-rendered, because those are the pages a crawler does not need and a reader reaches by navigating rather than by landing.

Head tags come from one component fed by a single site config, so canonical URLs, social cards and structured data are all derived from one origin string and are baked into the prerendered HTML rather than applied after hydration. Full page template previews get their own route outside the site layout, with no navigation bar, so a template can be framed in the docs or opened standalone and fill the viewport as its own page.