A component browser to prototype, demo, document, and publish React components
Platform | CI Status |
---|---|
Linux | |
OSX | |
Windows |
See a live demo of the components
The demo component browser includes:
- Rendered example components that are included in this library
- Code snippets used to generate the example components
- Component prop options, including default values and requirements
- Pre-requisites
- Installation
- Documentation Building
- Running the Project
- Project Details
- Testing
- Code Coverage
- Webpack
- Releasing
- Deployment
- Folder Structure
- Documentation Upkeep
- Contributing
- Troubleshooting
- Bug Reporting
The following applications must be installed on your machine prior to installation
Choose one of the following ways below to install the project (Git or .zip)
- In a terminal, change to a directory you would like to clone this project into
cd <YOUR_DIRECTORY>
- Clone the project
git clone https://github.com/roboholix/component-browser.git
- Change into the project directory and run:
cd component-browser && npm install
Skip if you ran the git clone
command above
- Download the .zip file.
- Extract the
.zip
file contents with your unzipping tool of choice - In a terminal, change to the directory of the unzipped project
cd /path/to/your/project
npm run build:docs
Files in the ./src/docs
folder have a standardized format of code commenting
used to extract and generate documentation for sample components running in the
component browser.
If you haven't already, run the build:all
command to build a plethora of things
including documentation, compiled css files, lib, dist, etc.
npm run build:all
Then, run the following command in your terminal:
npm start
Your default browser should automatically open up to the UI along with the server.
- UI - Runs on "http://localhost:8080"
This project serves as a React component prototyper, tester, component browser and npm package publisher all-in-one.
./src/components/
./src/docs
A folder containing example components to serve as "living documentation" when browsing components through the component browser.
Unit testing and end-to-end testing has been setup for this repo.
Run npm test
for both unit and end-to-end tests to run.
Jest has been used for the test framework.
Tests should be placed along with each component, using a *.spec.js
filename.
Cypress has been chosen for end-to-end testing.
Component specific Cypress tests should be placed in the component folder with a
filename of *.cypress.spec.js
, alongside any other unit tests that may exist
for that component.
Globally applicable e2e tests should be placed in the /cypress/integration/
folder
with a filename of *.cypress.spec.js
.
Jest snapshot testing is utilized in this repo.
Snapshot tests are stored in a component's __snapshots__
folder, with a filename
of *.spec.js.snap
.
Code coverage is available and ready for e2e and unit testing.
To manually run jest unit test coverage reports type the following command into your terminal:
npm run test:jest
Jest reports will be output to the jest-coverage
directory of this project.
To manually run cypress end-to-end test coverage reports type the following command into your terminal:
npm run test:cy
Cypress coverage reports will be output to the cypress-coverage
directory of this project.
npm run test
, npm test
, or just npm t
will all run unit and e2e tests with coverage
reports, and combine the coverage reports (via the posttest
npm script) into the
coverage
directory of this project.
Run npm run test:open-coverage
to see a combined report of unit test and end-to-end test coverage.
The combined coverage strategy used in this repo was taken from examples and directions at https://github.com/bahmutov/cypress-and-jest/blob/master/package.json.
Common webpack build tasks between development and production modes are stored in the
webpack.common.js
file.
Development webpack build tasks are specified in the webpack.dev.js
file.
Production webpack build tasks are specified in the webpack.prod.js
file.
To view a detailed visual analysis of the production build bundle, run the following command:
npm run analyze-bundle
To run a changelog update:
curl -H "Accept: application/json" -H "Authorization: token ${GITHUB_TOKEN}" --request POST --data '{"event_type": "autochangelog"}' https://api.github.com/repos/roboholix/component-browser/dispatches
See .github/workflows/*yml
for details on GitHub actions that handle automated releasing tasks
and CHANGELOG.md updates.
To deploy "living" documentation to gh-pages run:
npm deploy:docs
- IMPORTANT! READ ON...*
The package.json
in the root directory of this repo is a TEMPLATE to generate the package.json
that ends up getting published to npm.
To see the package.json
contents for the published package, you must first have ran the
npm run build:lib
command. After running the lib build task, you can view the generated
npm release's package.json
in /lib/package.json
.
- Merge and commit changes for new release
- Increment
/package.json
's version - Run
npm run build:lib
- Commit changes
- Push changes to master branch
- In the root directory of this repo, run
cd lib && npm publish && cd ..
https://github.com/roboholix/component-browser/
https://roboholix.github.io/component-browser/
- "Living" documentation should be published to Github's gh-pages at https://roboholix.github.io/component-browser/
EADDRINUSE means another process is using the same port you are trying to run
this project on. Attempt to find which other process is using port 8080.
Most likely the other process will be a previous instance of node, perhaps this
same project still running a npm start
in another terminal.
Try killing the other process using port 8080 and try again.
For other errors, try running npm install
again.
Try running npm run build:docs
Ensure you have all of the tools installed on your system under the Pre-requisites section.
Run npm install
again. If that fails, try removing the project's node_modules
directory
and run npm install
again.
Still having issues?
Click here to report any bugs or open a general issue with this package.