faqs
Frequently asked questions about the GentleDuck organization and ecosystem.
Any question that might be related to GentleDuck, our ecosystem, or how the tools fit together can live here. If you cannot find what you need, open an issue or discussion on our GitHub org: https://github.com/gentleeduck
GentleDuck is an open source organization building production-grade developer tooling. The ecosystem spans UI and interaction libraries, TypeScript utilities, CLIs, compiler and codegen tooling, testing frameworks, and systems utilities.
We build a connected set of libraries across the stack: design systems and registries (duck-www, registry-*), UI foundations (duck-primitives), utilities (duck-libs, duck-variants, duck-lazy), developer workflows (duck-cli, duck-template), compiler and codegen tooling (duck-gen), testing (duck-ttest), and systems and performance tools (TTLog, duck-benchmark, editor and Linux utilities).
Real products are not one dependency. UI, docs, codegen, installs, testing, and performance tooling all interact. Shared conventions and composable pieces let teams adopt one tool at a time, or stack several together.
Start with what you need most:
- Building UI: start with duck-www and duck-primitives.
- Shipping faster: start with duck-cli and templates.
- Reducing boilerplate: start with duck-gen.
- Type safety and reliability: start with duck-ttest, and then add query and state tooling as needed.
- Performance and debugging: start with TTLog and benchmarking tools.
No. UI is one part of the ecosystem. We also ship compiler and codegen tooling, CLIs, testing frameworks, state and data tooling, and systems utilities. The goal is end-to-end developer tooling that stays coherent.
duck-www is inspired by good patterns across the ecosystem, but it is designed as part of a broader platform with its own primitives, registries, utilities, and automation. The focus is cohesive workflows and production use, not copying a single library.
Primitives are the accessibility-first, unstyled building blocks. duck-www is the production-ready component layer and registry that builds on top of primitives with styling, variants, blocks, examples, and higher-level patterns.
Registries are how components, blocks, examples, and build outputs are organized and distributed across apps. They make it easier to install, sync, and keep product surfaces consistent across teams and repos.
The CLI is the workflow layer: initializing projects, installing packages, adding components or blocks, syncing registries, and automating repetitive setup. It is designed to keep installs predictable and reduce “copy paste” drift across projects.
Example:
npx @gentleduck/cli init
duck-gen is compiler-style tooling for generating type-safe routes, message tags, and integrations. The goal is to reduce boilerplate and enforce contracts so teams can iterate faster without losing correctness.
Yes. Query tooling is part of the ecosystem roadmap and package set, alongside state and other reliability tools. The goal is to provide predictable data access patterns that fit cleanly with the rest of the ecosystem.
duck-ttest is a TypeScript type-level testing framework. It lets you assert expected types at compile time, which is especially useful for utilities, variant systems, and any library where type guarantees are part of the API.
The ecosystem includes systems-grade utilities like TTLog (high-throughput logging), benchmarking tools (duck-benchmark), and workflow helpers such as Linux and editor tooling. These tools focus on observability, debugging, and runtime efficiency.
Yes. Documentation and content workflows are a first-class part of the ecosystem. The goal is to keep product docs, references, and integration guides consistent and easy to maintain as the toolset grows.
React-based frameworks are a primary target for the UI ecosystem (Next.js, Remix, Vite, and similar). Many tools are framework-agnostic by design, especially compiler and codegen tooling, CLIs, utilities, and systems libraries.
TypeScript is strongly supported across the ecosystem. Many libraries are designed with type safety as part of the API. If you are using plain JavaScript, some packages will still work, but you will get the best experience with TypeScript.
Accessibility is a core requirement for primitives and UI components. Keyboard navigation, focus management, and sensible ARIA patterns are treated as default expectations, not optional extras.
The ecosystem is built around composition. You can use primitives to build your own components, use variants to define consistent styling APIs, and use registries and blocks as starting points. You can adopt the pieces you want without being locked into a single opinion.
Many packages are designed specifically for production use, with an emphasis on performance, stability, and predictable APIs. Some packages are marked as under development or planned, and those should be treated as evolving.
We aim for clear changelogs and predictable releases. When breaking changes happen, we try to provide migration notes and keep changes scoped. If you adopt incrementally, you can upgrade one surface at a time.
A monorepo approach makes it easier to keep shared conventions aligned across packages, registries, docs, and apps. It also improves release consistency and cross-package refactors.
Please use responsible disclosure. If your report is sensitive, email the security contact listed by the org
(for example: security@gentleduck.org) or use the GitHub
security advisory flow when available for a repo.
Most projects are MIT-licensed. Always check the specific repository for the authoritative license text.
Contributions are welcome: bug reports, docs fixes, feature requests, and PRs. Start by opening an issue describing what you want to change and why. If you want to add a new package, we usually prefer aligning on scope and naming first to keep the ecosystem cohesive.
Yes, the ecosystem is intentionally expanding: UI, docs, codegen, testing, state, query, and systems tools. The best place to track what is shipping next is the GitHub org issues, PRs, and release notes.
Usually yes. We try to keep APIs familiar where it makes sense, and we design for incremental adoption. You can replace one piece at a time: start with variants, or primitives, or a single UI component, then expand as needed.
The projects are open source and community-driven. If you need dedicated help for migration, integrations, or internal tooling, open a GitHub discussion to start the conversation.
The default expectation is no hidden telemetry. If any tool ever needs optional diagnostics, it should be clearly documented, opt-in, and easy to disable.
We aim for modern builds that work well with current bundlers and support tree-shaking where applicable. If you hit a bundler or module format issue, open an issue with your reproduction and environment details.
Docs are distributed per product site and repo. In general:
- Main org site: gentleduck.org
- UI docs: gentleduck.org
- Codegen docs: gen.gentleduck.org
- Source of truth and issues: GitHub org repositories
The naming reflects ecosystem grouping and makes it easier to discover related tooling. For example: duck-www, duck-primitives, duck-variants, duck-gen, duck-cli, duck-benchmark, duck-ttest, and registry packages.
Open a GitHub issue or discussion in the most relevant repository, include your goal, your environment, and a small reproduction if it is a bug. If you are not sure which repo fits, start at the org level and we will route it.