BUG - Sev-3 - All - Storybook complains about missing dist/ folder in local dev environment

[narin]

What happened?

In our dev environment, the components package is using a local version of the tokens package instead of pulling down a remote version from NPM. This causes errors in our storybook app if the developer hasn't run yarn build in the tokens package. The components package relies on files in the dist/ folder of tokens, which is currently in our .gitignore file.

Steps to Reproduce

1. Delete any dist/ folder in packages/tokens
2. Try to run Storybook iOS
3. An error will show regarding missing files from the dist/ folder.

Desired behavior

1. Storybook should run without errors

Acceptance Criteria

• Update our yarn configuration to pull down the remote version of our design tokens package OR
• Remove the dist/ folder from our .gitignore OR
• Document building the tokens as part of the setup guide

[TimRoe]

The direction of this ticket after much troubleshooting was decided to be:

1. Adding a new convenience script (tokensBuild) to the components package that builds the tokens easily
2. Adding guidance to the components package README to ensure it is run as part of initial setup

To document why this was the chosen direction:
Issues encountered that I posted in Slack:

First: I came across this SO comment that matches my initial thoughts that our intended fix doesn't jive with the entire intent around workspaces--by design, they are supposed to make it so it uses the local instead of remote code so you can work on the projects directly together w/o publishing

Trying the enableTransparentWorkspaces: false workaround in that same SO thread, I could not for the life of me get that to work--it still kept going to the local file. Part of this may be that I also realized that having the yarn.lock in the components package is breaking the workspaces when running from within the components package (works fine from root directory) so that it only registers the workspace root and not the tokens runningyarn workspaces list and can not run global scripts: e.g. can't run the token build script from within components (or even root level scripts like yarn lint)

However, when I have yarn workspaces working from within the components directory without the yarn.lock, it never installs node_modules at the package level so then I get errors around missing those since it doesn't revert to looking at the workspace node_modules that has them. At least with some minor digging, I couldn't find a way to repoint it to look up to the root directory for node_modules, but it should be possible (?, thought it should be automatic). FWIW: with the enableTransparentWorkspaces flag false, the yarn.lock in the root directory did separate out the remote version of tokens and the workspace one so theoretically it would work to leverage the remote one if fixed

So not sure if either of you had any wisdom around how this config could be made to work "correctly." Bearing in mind, as far as I can tell it is and it's just correct that workspaces will use the local version of the code. Also that flag is global from the workspace root, so we'd need to manually turn on on a package-by-package basis to work locally if we got it working (in theory setting package versions to workspace:^#.#.# ... I also had no luck getting that working)

My intended hacky solution was just having a script in the component library that just manually cd's to the tokens, runs the build, and then moves back--and longer term if we had additional scenarios maybe we'd want to have a repo-level script that builds all packages that need it

Upon trying to move forward with the hacky solution with it configured as a preinstall script (in theory runs before every install), it only worked intermittently. It worked if the node_modules did not exist, but if they already existed and had no changes then it did not work. As far as I can tell, this is a sporadically fixed then unfixed npm bug wherein preinstall/postinstall scripts and the like do not always run correctly. Additionally, looking around the documentation into why it wasn't working, I came across the yarn documentation that explicitly indicates:

Postinstall scripts have should be avoided at all cost, as they make installs slower and riskier. Many users will refuse to install dependencies that have postinstall scripts. Additionally, since the output isn't shown out of the box, using them to print a message to the user will not work as you expect.

which made me recognize that the script may try to run when packaged up and consumed by an app--which wouldn't work trying to navigate to a directory that didn't exist. In theory logic could be made to circumvent that problem, but paired with it only intermittently working as desired in the project it seems sensible to just drop automatically handling it. As such, we arrive at the solution documented at the top of this comment.

[TimRoe]

Created tickets:

• 7193 for the yarn workspaces problems
• 7194 for a potential code upkeep that could simplify structure of the components package
• PR link