20. Using shadcn as our component library
20. Using shadcn as our component library
Section titled “20. Using shadcn as our component library”Date: 2025-04-19
Status
Section titled “Status”Accepted
Context
Section titled “Context”When we initially built our component library, we relied on basic Tailwind CSS for styling and component creation. This approach gave us flexibility but required significant effort to maintain consistency and implement complex interactive components.
As our application grew, we attempted to standardize by adopting HeadlessUI components. However, we encountered several challenges with HeadlessUI, particularly around version compatibility and testing. Our test suite frequently encountered issues with HeadlessUI components, as seen in our Dropdown component tests where we struggled with proper event handling and component rendering in the test environment.
We needed a more robust solution that would:
- Provide consistent, accessible components
- Work well with our testing infrastructure
- Be well-maintained and have good documentation
- Allow for customization to match our design system
- Standardize our approach across multiple applications
After researching alternatives, shadcn/ui emerged as a highly recommended solution in the React ecosystem, with strong community support and compatibility with our tech stack.
Decision
Section titled “Decision”We decided on shadcn/ui https://ui.shadcn.com/ as our Component LIbrary.
Consequences
Section titled “Consequences”What becomes easier:
Section titled “What becomes easier:”- Consistent, accessible components across all applications
- Better testing experience with reliable component behavior
- Reduced development time for common UI patterns
- Strong TypeScript support and type safety
- Active community and comprehensive documentation
- Copy-paste approach allows for easy customization
What becomes more difficult:
Section titled “What becomes more difficult:”- Migration effort required from existing HeadlessUI components
- Need to learn shadcn/ui patterns and conventions
- Potential bundle size increase compared to minimal custom components
Risks to mitigate:
Section titled “Risks to mitigate:”- Plan gradual migration strategy to avoid breaking existing functionality
- Ensure team training on shadcn/ui best practices
- Monitor bundle size impact and optimize as needed
- Establish guidelines for when to use shadcn components vs custom solutions