[RFC] rearchitect project to keep separate packages with single Storybook app

[brylie]

Problem

Our project is currently split into multiple packages each with its own Storybook instance. The separate packages are desirable so we can use them in downstream projects. However, having multiple Storybook instances has led to some breaking complexity and redundant configuration.

In effect, the complexity introduced by the underlying dependencies has become an impediment to further development.

Additionally, the package documentation should probably not be intermixed with package code (unless in the form of comments/docstrings).

Description

Determine how to rearchitect this project so that we have

• only one global Storybook project and
• separate packages for vocabulary, fonts, and vue-components (allowing packaged distribution)

With this architecture, we might then be able to deprecate lerna.

Example architecture

• /src/ or /packages/ - contains the sub-packages
  • fonts/ - fonts package (can possibly be merged into the vocabulary package)
  • vocabulary/ - vocabulary package (possibly including the fonts package)
  • vue-vocabulary/ - Vue components
• /docs/ - documentation project containing Storybook code
  • package.json - dependencies for Storybook project
  • imports for vocabulary packages might be defined in package.json or index.js

Related issue(s)

• https://github.com/creativecommons/vocabulary/issues/630

[brylie]

@dhruvkb would you consider offering your perspective and guidance regarding a simplified project structure where Storybook is decoupled from the vocabulary packages?

[dhruvkb]

I would absolutely love to, but I need a couple of days to play with Storybook before conclusively saying what would work for us. I'm still unsure if this is even possible with the way Storybook is architectured so I need to do a little bit of research on my end.

[brylie]

Sure thing. Take your time 😃

[dhruvkb]

@brylie I did some experimentation about having a single storybook for two intermingled projects (SCSS + Vue). I've hosted the most elegant solution I found at dhruvkb/vocab and it's Storybook at https://dhruvkb.github.io/vocab.

This repo contains one project with two build entrypoints, one producing a combined stylesheet and the other producing a Vue library. Some features of this approach include:

• minimum redundancy, both in terms of code and config
• maximum code sharing, both within the project as well as for a single Storybook
• very simplified dev process, Vue and SCSS are developed together
• a more maintainable unified codebase instead of three smaller ones
• easier for new developers; no need to learn any tooling like Lerna (I still don't know how it works so... 🤷‍♂️)

I personally like this solution a lot, especially because of the relatively straightforward migration path from the current state to this one.

Could you check the project out and see if you feel this direction would be beneficial to move forward?

[brylie]

@dhruvkb thank you so much! I am checking the code out now. Would you try an experiment to see if the solution you have made can be deployed to GitHub pages with the storybook-deployer? I.e.it would be useful to have a single command to build/deploy the latest project release for continuous integration.

[brylie]

@dhruvkb would you mind if I assign you to this task so we can track its resolution? It is a high priority in our active sprint 😃

[dhruvkb]

Yeah, sure. I don't mind! 😄 Do you agree with the direction taken in the test repo?

[brylie]

Yes, the repo architecture looks great! 😎 🏗️

The only change I suggest is that we avoid keeping the generated output in revision control. Keeping static generated output in revision control makes for noisy pull requests and repository bloat.

The build system/script can typically generate the output in a dedicated branch for GitHub pages or Netlify. So, I recommend we add a .gitignore rule to exclude the /docs directory and investigate how the deployment will generate the static files in a separate task.

[dhruvkb]

@brylie putting the Storybook in the docs/ directory was a quick hack to get the Storybook live for a demo, that's definitely not what I intended to do in production 😆.

[dhruvkb]

I've started working on this in a separate restructure branch. We can discussion the implementation specifics on the ^draft PR. Reviews, feedback and contributions to it are welcome 😄!

[github-actions]

Stale issue message

[brylie]

@dhruvkb have you had a chance to review pull request #940?

[dhruvkb]

Really sorry @brylie and @sadn1ck for all the delays I've caused in the review. I got caught up in work a little more than usual. I'll definitely review this today and take this through to completion if there are any changes to be made.