docs: Add ADR 004 - Component Library Restructure #1871
Conversation
Proposes renaming /storybook to /core and establishing it as the primary location for library components with gradual migration from the current scattered structure. ## Context - Current library components are scattered throughout /app directory - Need clear separation between library and application-specific code - Opportunity to modernize build system based on successful Vite adoption ## Proposed Solution - Rename /storybook → /core to reflect library purpose - Gradual migration strategy with backward compatibility - Dual build system during transition (legacy Parcel + new Vite) - Re-export strategy to avoid immediate component copying - Future state: standalone /core package ## Benefits - Modern development environment with Vite - Clear component library boundaries - Unified documentation and development - Future-proof architecture for standalone library - Low-risk incremental migration path Addresses the natural evolution from the successful split architecture that enabled Storybook development, building on proven Vite benefits.
✅ Deploy Preview for veda-ui ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Hi @AliceR, thanks for putting this ADR together, this is much needed. I agree with the problem statement and the decision to give our component library a proper home. Thinking about the long term, I’d like to propose a small shift. My view is that the component library should be a standalone package, and apps like Storybook or the legacy SPA should be separated from it. Storybook is just a dev viewer for components (and potentially a docs website in the future), and the SPA in That’s why I think it makes sense to set up a monorepo with /packages and /apps. It gives us the target structure right away, and the migration then becomes about moving things into the right place. Proposed steps Step 1 – Create structure Step 2 – Start migrating components Step 3 – Move Storybook Step 4 – Isolate legacy SPA and shared code Why this path
This follows the spirit of your ADR but pushes us to a more conventional and future-proof end state. |
|
How does this approach integrate with the plugin framework repo that we recently started, and with this idea that the plugin marketplace will have plugins made from components outside of veda-ui? |
|
@AliceR given that we are entering maintenance mode on veda-ui and focusing on bug fixes and maintenance tasks, do you think we should close this? |
|
We could also merge it as "proposed", for posterity – what do you think? |
|
I think we can merge, but could we update the ADR to reference this PR and #1898? That one introduced the monorepo structure we discussed in check-ins, and linking both would help preserve the context. |
|
It would be nice to hear feedback from the rest of the team on this ADR. |
|
If the goal is simply to move files, and introduce a new build (while maintaining the old), I'm not sure it's worth the time. If this is just phase 1 of a committed larger refactor by more than a couple individuals, that makes sense! Very keen on these broad goals:
Assuming this is just phase 1, here's some thoughts from my end (but please note I'm not familiar with the depths of this repo, so my approach could be off!!!) Suggestions
Concerns:
|
|
@ifsimicoded thanks for the feedback. I agree we should define concrete actions to get this across the finish line, especially since the PR has been open for more than 60 days. My proposed scope is:
Out of scope
|
|
@vgeorge apologies for the delay! You're free to move things around but I'm not sure that actually addresses the larger concerns I've heard voiced and i've personally experienced about working with
|
- Document evolution from Option C to Option D (monorepo structure) - Update status to reflect PR #1898 merge - Add action items from PR #1871 discussion - Capture ifsimicoded's concerns about broader developer experience - Update implementation plan to reflect actual monorepo structure - Remove outdated /core references and verbose content
|
Hi @ifsimicoded, thanks for the feedback! I’ve updated the ADR to capture the broader developer-experience concerns you raised. I’ve also moved forward with PR #1898 together with @dzole0311, which initializes the monorepo structure by relocating the library to packages/veda-ui/. That PR is now merged. I’ll continue with the remaining migrations (Storybook to apps/storybook/, SPA to apps/legacy-spa/) as outlined. Once this work is finished, I’ll update the ADR to document the outcome. Please let me know if you have any additional feedback. I’ve converted this PR to draft until we conclude the migration. |
Add brief VEDA2 background pointer and reference link.
Update header metadata to reflect decision acceptance.
Reduce verbosity and clarify pre-monorepo pain points.
Keep /core proposal while shortening trade-offs and consequences.
Replace repeated end-of-doc consequences with a trade-offs list under option D.
Reinstate key pros/cons for the original /core and Storybook proposals.
Keep packages/apps intent while leaving Storybook placement flexible.
Point build tooling follow-up to v7 roadmap and build tooling issue.
Keep only ADR 006, architecture docs, and ADR PR.
Reference ADR 004 alongside ADR 006 for VEDA2 and monorepo direction.
Make ADR links in ARCHITECTURE easier to scan.
|
@ifsimicoded @dzole0311 As we are moving forward with the monorepo approach, I believe it makes sense to merge this PR as accepted. I did an overhaul of the documentation to make it easier to read. I tried to keep the main points of the original document, please let me know if I left something important out. This is ready for review. |
ifsimicoded
left a comment
ifsimicoded
left a comment
There was a problem hiding this comment.
Thanks for continuing to push through on keeping this repo documented and organized. I'm excited to co-plan a strategy for "v7"
|
Great, thank you! |
Proposes renaming
/storybookto/coreand establishing it as the primary location for library components with gradual migration from the current scattered structure.Context
Proposed Solution
/corepackageBenefits
With this setup, it will be much easier to keep track of our refactor and migration work!
Update: After this discussion, there was a slight shift in direction. Instead of renaming /storybook to /core, we’re moving toward a monorepo-based structure where the library lives under packages/veda-ui/. The goals and motivations below still apply.
Action items:
apps/legacy-spaapps/storybook