VitePress Valence v0.2.* Released
I've spent the past few weeks working on a large update to VitePress Valence, my component library for VitePress sites. Version 0.2.* brings together new features, visual improvements, and a focus on consistency across the entire package.
The most visible change is the styling overhaul. Components now share a cohesive design language with more polished visuals. Beyond the surface changes, I've standardized the usage patterns, data loaders, and frontmatter structures to be more predictable and uniform across components.
I've also streamlined the development workflow by consolidating global styles and functions, and set up better tooling for local development. The package also now has a comprehensive documentation site that covers all components with examples and detailed references.
You can explore the full documentation at vitepress-valence.cynber.dev.
Some Background
Over the past few years, I've worked with various static site generators before settling on VitePress for several projects. I appreciated its clean default styling and the ease of integrating custom Vue components for specific functionality. When recommending VitePress to peers for documentation and content-heavy sites, I often found myself creating similar components for them across different projects.
Managing duplicate components across multiple repositories became cumbersome since I was making changes in several places. This led me to extract these components into a shared library that could be imported and reused.
The original library grew organically from these individual projects, resulting in a collection of useful but inconsistent components, each with their own visuals and usage patterns. This update addresses that inconsistency.
Updating to v0.2.*
The good news is that most updates are backwards compatible. You can upgrade to get the new visual improvements without breaking existing functionality. However, there are some important changes to be aware of:
Component Name Changes
All components now use the Vpv prefix to avoid naming conflicts with other libraries or your own components. The old component names are still available for backwards compatibility, but I recommend migrating to the new names:
Component Migration Guide
| Old Components | New Component | Notes |
|---|---|---|
HorizontalCard | VpvCardHorizontal | |
VerticalCard | VpvCardVertical | |
HorizontalContainer | VpvContainerHorizontal | |
VerticalContainer | VpvContainerVertical | |
JSONTable | VpvTableJSON | |
ImageGallery | VpvImageGallery | |
VpvImage | New component | |
EmbedLemmy | VpvEmbedLemmy | |
EmbedMailchimpSubscribe | VpvEmbedMailchimp | |
BlogPostHeader | VpvArticleHeader | Requires new frontmatter structure |
BlogPostsVerticalBlogPostsHorizontalBlogPostList | VpvArticleList | Requires new frontmatter structure |
HeaderCard | Now integrated into container components as props |
Article Components and Frontmatter
Pay close attention to the new frontmatter structure for article components. For example, the banner field has been renamed to featured_image and now includes additional options like alt and description.
https://vitepress-valence.cynber.dev/guide/article/create-post
Header Component Removal The standalone HeaderCard component has been removed. This functionality is now built into container components using header-prefixed props.
https://vitepress-valence.cynber.dev/guide/cards/usage#optional-header-functionality
Other Breaking Changes
I've tried to maintain backwards compatibility wherever possible, but if something breaks during your migration, please let me know so I can update this guide and address any issues.
Other Key Changes
Beyond the major updates covered above, this release includes several improvements/fixes:
Image Handling
The new image options across all components now support separate images for light and dark themes, custom aspect ratios, and proper alt text and descriptions for better accessibility.
Responsive Design Improvements
The components now follow VitePress's default breakpoints, ensuring your content responds to screen size changes at the same time as your site's navigation and layout. For example, the new masonry layout for image galleries automatically adjusts column counts based on screen size.
Better Data Consistency
Fixed several issues with data loaders that were causing inconsistent image display in galleries and time zone problems with article dates. I also fixed the hydration mismatch issue with PhotoSwipe, which was causing the component to not work properly on initial load.
Thank You!
If you build something with this library, I'd love to see it!
If you have any questions or feedback, please don't hesitate to reach out.
Links:
- GitHub
- Bugs/Feature Requests
- NPM
- Message me on Lemmy