This application is an example of creating and documenting a Design System using Storybook with Monorepo structure.
Access the Design System online through this link.
This project uses a Monorepo structure, basically there are 5 projects in only one repository, this helps a lot the codebase maintainability, the dependencies are centralized in the project root, and not in each individual package, with this structure it is possible to use another package as a dependency in a more simplified way.
Example of package structuring:
├── design-system/
│ ├── packages/
│ │ ├── docs/
│ │ ├── eslint-config/
│ │ ├── react/
│ │ ├── tokens/
│ │ └── ts-config/
│ ├── package.json
│ ├── package-lock.json
│ └── turbo.json
Turborepo is a smart build system for JavaScript/TypeScript monorepos: codebases containing multiple projects, often using multiple frameworks, in a single, unified code repository.
Using Turborepo, a dev script was created that executes all packages that have the same script in parallel, in addition, a build script was created that generates the build of all packages in an intelligent way, generating a cache so that the next build will be very fast.
See more:
Changesets is widely used when we have public packages that are going to be published in NPM, this tool helps to control the versioning of our monorepo, because as we have several packages in this project, and each one of them will be an individual package in NPM, and these packages can having different versions and different changelogs, that is, they are changes that happen over time in these packages, and controlling all this simply on GitHub is not so simple, because it ends up affecting all the project as a whole, but Changesets comes to help us in that.
See more:
The components developed were these:
In the section below, the deployment process will be discussed, but before carrying out these procedures, it is necessary to change the name of the organization @sup3r-us3r, defined in each package and in other places of the application, to what you define in the act of organization creation in NPM, due to the amount of files to change if you use for example VSCode to edit your codebase, you can use the Search function, search for that name and change it to what you define in all files at once.
In this project, the Design System documentation is done with Storybook, and there is a CI/CD flow to publish this documentation online, using GitHub Pages, which is a free hosting that GitHub offers.
Some settings are required, follow the steps below to configure correctly:
Change the value of the string '/design-system-with-storybook/' from the file main.js located in packages/docs/.storybook/main.js to the name of your repository on GitHub.
...
viteFinal: (config, { configType }) => {
if (configType === 'PRODUCTION') {
config.base = '/design-system-with-storybook/'
}
return config
}
...Now run the action Deploy docs to publish the Storybook, this will automatically create a branch in your repository called gh-pages, it is in this branch which will store the content of the Storybook in production.
Finally, go to Settings - Pages of your GitHub repository, make the following changes:
- Source: change to Deploy from a branch
- Branch: change to gh-pages /root and click Save
You must have an NPM account to have packages published automatically, then you must create an organization in NPM so that your packages are linked to an organization.
To do this, access the NPM website and go to Add Organization
Now it is necessary to generate a Token to be able to publish the packages using GitHub Actions, to generate a Token go to the Access Token option, and then click on Generate New Token, define the Automation type and then copy the Token that will be generated.
Now access your repository on GitHub go to Settings - Secrets - Actions - New repository secret.
Create a secret called NPM_TOKEN with the Token value copied earlier.
To make the build faster, we can use a caching strategy that Turborepo provides, but since we are using an external CI/CD stream we need to send this cache somewhere, and Vercel has a free Turborepo integration, so we can send this cache, and so the next build will be much faster, the feature in question is Vercel Remote Caching.
To use this feature it is necessary to create 2 secrets on GitHub, then access your repository on GitHub go to Settings - Secrets - Actions - New repository secret, create the 2 secrets below:
TURBO_TOKEN: A Vercel Access TokenTURBO_TEAM: The slug of the Vercel team or username
To create the Access Token at Vercel is very simple, just access the Settings - Tokens tab or use this link, now click Create, set a name for your Token, a scope and expiration date and click on CREATE TOKEN.
See more:
Install dependencies:
$ npm iRun in development mode:
$ npm run devRun the local build:
$ npm run build