@roboholix/component-browser

Component Browser


Keywords
roboholix, react, react-component, resize, scale, aspect ratio, game, arcade, video
License
Unlicense
Install
npm install @roboholix/component-browser@0.0.3

Documentation

Component Browser


A component browser to prototype, demo, document, and publish React components

Platform CI Status
Linux Linux Build Status
OSX OSX Build Status
Windows Windows Build status

Quick-start Demo (with example code)

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

Table of Contents

Pre-requisites

The following applications must be installed on your machine prior to installation

Installation

Choose one of the following ways below to install the project (Git or .zip)

Git Install

  1. In a terminal, change to a directory you would like to clone this project into cd <YOUR_DIRECTORY>
  2. Clone the project git clone https://github.com/roboholix/component-browser.git
  3. Change into the project directory and run: cd component-browser && npm install

Zip File Install

Skip if you ran the git clone command above

  1. Download the .zip file.
  2. Extract the .zip file contents with your unzipping tool of choice
  3. In a terminal, change to the directory of the unzipped project cd /path/to/your/project

Documentation building

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.

Running the project

If you haven't already, run the build:all command to build a plethora of things including documentation, compiled css files, lib, dist, etc.

  1. npm run build:all

Then, run the following command in your terminal:

  1. npm start

Your default browser should automatically open up to the UI along with the server.

Project Details

This project serves as a React component prototyper, tester, component browser and npm package publisher all-in-one.

Components Folder

./src/components/

Documentation Folder

./src/docs

A folder containing example components to serve as "living documentation" when browsing components through the component browser.

Testing

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.

Unit Tests

Jest has been used for the test framework.

Tests should be placed along with each component, using a *.spec.js filename.

End-to-end Tests

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.

Snapshot Tests

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

Code coverage is available and ready for e2e and unit testing.

Unit Testing Coverage

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.

End-to-end Coverage

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.

Combining Coverage Reports

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.

Webpack

Common webpack build tasks between development and production modes are stored in the webpack.common.js file.

Development

Development webpack build tasks are specified in the webpack.dev.js file.

Production

Production webpack build tasks are specified in the webpack.prod.js file.

Bundle Analyizer

To view a detailed visual analysis of the production build bundle, run the following command: npm run analyze-bundle

Releasing

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.

Deployment

To deploy "living" documentation to gh-pages run: npm deploy:docs

Npm packages

  • 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.

Publishing

  1. Merge and commit changes for new release
  2. Increment /package.json's version
  3. Run npm run build:lib
  4. Commit changes
  5. Push changes to master branch
  6. In the root directory of this repo, run cd lib && npm publish && cd ..

Github

https://github.com/roboholix/component-browser/

Github Pages

https://roboholix.github.io/component-browser/

Folder Structure

Documentation Upkeep

Contributing

Contributing

Troubleshooting

npm errors or EADDRINUSE

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.

No documentation or errors related to documentation building

Try running npm run build:docs

Other build issues

Ensure you have all of the tools installed on your system under the Pre-requisites section.

Missing dependencies

Run npm install again. If that fails, try removing the project's node_modules directory and run npm install again.

Bug Reporting

Still having issues?

Click here to report any bugs or open a general issue with this package.