Repository navigation
FAQ
Which Node version do I need? Node >= 20 to use the CLI. Developing the Framebits repo itself needs Node >= 22 with pnpm.
Why pnpm only? One lockfile, one toolchain — it keeps installs deterministic and CI honest. npm/yarn/bun lockfiles are used for detection of your package manager, but this repo builds with pnpm.
Does init modify my configs?
No. It writes only framebits.json — never tsconfig, Tailwind config, or
package.json. Running it twice is safe.
Tailwind v3 or v4?
Both. init detects v3 (config file) vs v4 (@import "tailwindcss" in CSS)
and add merges styles in the matching form. If it can't patch safely, it
prints exact manual steps instead of corrupting your files.
I got exit code 4 (integrity failure). Can I skip the check? No — there is no skip flag, deliberately. Re-run the command; if a hash mismatch persists, report it. The allowlist + hash verification is the real anti-compromise defense.
Does the CLI phone home?
add sends one fire-and-forget install event (1.5 s timeout, failures
swallowed). First run prints a notice. Fully disabled by
FRAMEBITS_TELEMETRY=0, DO_NOT_TRACK=1, --no-telemetry, or --dry-run.
Never sends paths, project names, or file contents.
Does it work offline / in CI?
Reads come from the static registry; search/list (when they land) work
from a local cache. In non-TTY/CI environments the CLI never prompts —
use --yes/--overwrite or it fails clearly instead of hanging.
Why is a component draft / invisible?
Drafts never leave the builder — they're works in progress. Only
published (and deprecated) ship to the CLI and the site.
Why can't a component be deleted? Stats must survive. Deprecate instead — versioned archives stay immutable.
Why do catalog cards show images instead of live demos? Performance and safety: cards render static WebP only. The live demo runs exclusively in the sandboxed iframe on the detail page.
Windows setup?
Use WSL2 or Git Bash so shell scripts keep LF endings (enforced by
.gitattributes). The CLI binary itself runs on plain Windows.
Where do I change a schema?
packages/shared — and only there. Every other package imports and infers.
Duplicate types are a build smell.
Checks failing on my PR?
Run the full gate locally: pnpm build && pnpm lint && pnpm typecheck && pnpm test, plus pnpm build:registry --check for registry changes.
Still stuck? → https://github.com/otassh/framebits/issues
The normative spec lives in the repo:
docs/MASTER_PROMPT.md. If this wiki contradicts the repo, the repo wins — please open an issue.