Welcome to the CGUI react library, with component syncing to bit.dev.
After pulling down this repository, you'll need to set up a connection between your machine, the repo, and the bit.dev server.
If you aren't yet familiar with the Bit system and architecture, please review their documentation before contributing to this project.
First, ensure Bit is installed globally on your machine. You can find instructions for installing Bit here: https://docs.Bit.dev/docs/installation
Once Bit is installed locally, you will need to ensure your local components in the repo are synced with Bit.
It is important that you import before any new work is started on an existing component. Much like rebasing with git, if you start work on an existing component without pulling in the newest changes from remote, you will end up with merge conflicts.
run yarn sync
to automatically import and list component states for changed components in the Bit.dev repository.
Our Bit architecture uses the proposed Centralized Library workflow described here.
This workflow allows us to use this repo (synced with the bit.dev repository) as the source of truth for all of our react components. This also works as a backup for our react library in the event of an outage or other availability issues with the bit.dev server.
This architecture also allows us to properly test our components thoroughly before using them in production projects.
Be aware that our development process for this repo is different from other repos. Instead of updating git and adding a PR prior to publishing/deploying your component changes to bit.dev, you'll want to instead push all of your updates to bit.dev before creating your PR or merging to github. This is because deploying to bit.dev will change files in your repo which would require you to push additional changes to github.
Because your are publishing your changes before having them merged to source control it is very important that you thoroughly test and review your changes prior to deploying them to bit.dev. Ensure you add new jest tests to cover new component changes to help validate your updates as well.
When working on an existing component in the library, first be sure to run yarn sync
to import the latest versions of all components. This is important since components can be updated outside of this working repository.
Once you have imported the component, you can work on your improvements as needed. Keep in mind that all components should have full unit test coverage of their functionality and logic.
Run bit status
at any time to see the status of tracked components.
Once you have finished work on a tracked component you should build it to ensure it compiles without errors: bit build <component_id>
Once you have ensured your component builds correctly, you can tag it with a new version for release. bit tag --all
will automatically bump version numbers to the next patch or minor release as needed. To manually change the version number, use: bit tag <component_id> <new_version_number>
Once your component or components have been versioned, you can export them to the bit.dev server using: bit export campgladiator.cgui
If you come across any merge conflicts while exporting, this is likely a result of you not having the most recent version of a component pulled down locally.
You can learn more about fixing these types of merge conflicts here
First identify if you new component constitutes an atom, molecule, organism, template, or page based on the atomic design principle. This project has a folder for each grouping allowing you to keep your components organized by this paradigm.
To create your component, you can follow the structure you see used by other components in the repo. Set all component files up in a single folder named the same as the component. Include the main component file, along with a .scss file, if needed, a test/spec file and an index file which would allow exporting of the component by Bit. Finally, a markdown file should be added to the component folder with the same name as the component file (ex: Button.js would have a Button.md file). This markdown file is where you would put any documentation for the component including instructions on how to use it.
Once your component folder is structured, you'll want to set up tracking with your component and Bit. To do this run the following command:
bit add <local/path/to/ComponentFolder> --tests <local/path/to/ComponentFolder/component.spec.js> --namespace <components/component_folder>
In the above example <components/component_folder> would be something like components/atoms
, components/molecules
, components/organisms
etc. Which is the Bit namespace/folder that this component would be grouped with.
Example:
bit add src/components/atoms/Button --tests src/components/atoms/Button/Button.spec.js --namespace components/atoms
Next, we must tag our components with new versions. Bit will automatically bump version numbers of updated components when you run bit tag --all
Similar to git, we need to finally export our components up to the remote repository, in this case, bit.dev, is our remote. To do this, we just run the export command followed by the collection we want to export to:
bit export campgladiator.cgui
This will export any components that have been tracked and tagged with a new version.
With this done, your component(s) should now be available in the remote collection at: https://bit.dev/campgladiator/cgui
In addition to the .md file in the component directories, you can also add a general description to the component in bit.dev. Bit.dev also provides a sandbox where you should add examples of your component in use. Please see the bit.dev docs for more info about how to build examples: https://docs.bit.dev/docs/bit-dev#component-playground