unfoldingword-box3/hello-world-react-component-library

Hello World React Component Library

Example React Component Library

Read more about why we are focusing on creating component libraries and our approach: https://forum.door43.org/t/component-libraries/396

The Stack

• Javascript + React (functional components & hooks).
• MaterialUI for UI/UX baseline design components.
• Styleguidist for Playground Documentation.
• Yarn for dependencies, publishing, and deploying.
• Github + NPM + Github Pages for Hosting.

There are many alternatives to each layer referenced here. However, many of the alternatives add a great deal of complexity to the initial setup and long term maintenance which prevents it from being practical.

How to deploy your own?

Once you have this codebase forked and cloned to your local machine, you can start modifying the codebase. You will need to ensure node.js and yarn are already installed.

Installation and Running the Styleguide Locally

1. Install the npm dependencies with yarn.
2. Run the Styleguide with yarn start.
3. Ensure that the Styleguide is running by visiting localhost:6060 on your web browser.
4. Modify the code and documentation in your code editor and check out the Styleguide.
   • Update the styleguide.config.js to match your new component names.

Setting up NPM Publishing

1. Rename your library:
   • the folder
   • repo on Github
2. Update the package.json:
   • change the name and description of your app
   • change the URLs of your homepage and repository
3. Create an account on npmjs.org if you don't have one already.

Publishing to NPM

The scripts in the package.json file do all of the heavy lifting.

1. Commit and push all changes to your github repo.
2. Run yarn publish:
   • login to NPM using your credentials if asked.
   • enter the new version number using symver.
   • wait for the code to be transpiled and published to NPM.
   • wait for the styleguide to be built and deployed to GHPages.
3. Visit your published library on NPM.
4. Visit your deployed Styleguide on GHPages.

Deploying Styleguide to GHPages

You can optionally deploy the styleguide to GHPages without publishing to NPM.

1. Run yarn deploy
2. There is a predeploy hook that builds the Styleguide.
3. That's it!

Other Resources

Here's a great writeup that walks you through a slightly different stack: https://itnext.io/how-to-write-your-own-reusable-react-component-library-a57dc7c9a210

hello-world-react-component-library's Issues

Considers for this example component

@klappy I typed up some thoughts about my experience using this example library to learn React and to use it as the basis for my first component. Hopefully, this will improve and provide consistent and supportable components in the future.

• NPM registration results in versioning issues. At one point I “unpublished” my library, but when I tried to (re)register after the requisite 24 hours, it still would not accept the prior versions. I had to pick up at a subsequent version. This means NPM never really forgets both the name of the component and the latest version. This causes issues: a) If I develop under my Github account, then the component name will forever be associated to me; b) And unfoldingWord will have trouble using the component under that name. Using the “box 3” identity will have the same problems.
• Given this, some thought should be given to naming practices/standards for components.
  Of course, maybe there is something about using NPM registration I don’t know yet!
• I recommend a description of a typical workflow that iterates locally before trying to publish. Once things are working, it would be nice if we could deploy the Github pages without registering in NPM. At this point, It seems prudent to avoid NPM registration as long as possible.
  It was not clear to me, after working on this PoC, what purpose NPM component registration serves during development. I’m guessing that registration is needed at some point in order for unfoldingWord component dependencies to be resolved. But is it needed during development?
• Consider a React template project repo with documentation for us to use. The Hello World example functioned as the template at first, but had pieces missing -- mostly documentation:
  a) The layout of the project, where things go; b) Where file names are referenced inside Javascript code and where spelling is important
• Information on how to use the “test” scripts to set up unit tests for the component

Custom Badge Error?

In the README.md is a URL reference to coverage shields.json. This does not exist. Could be the source of the "internal error" on the badge??

[suggestion] Addition to .gitignore

Consider *.lock.

Reason: I received a security alert from Github about yarn.lock. AFAIK, neither it nor package.lock are needed in the repo.

Dependency missing: gh-pages

Publish problem: babel: not found

See transcript below for error. I think it may be due to missing line in package.json in devDependencies section: "@babel/cli": "^7.5.5",

Transcript:

$ yarn publish
yarn publish v1.19.2
[1/4] Bumping version...
info Current version: 0.0.1
question New version:
[2/4] Logging in...
info npm username: mandolyte
info npm email: [email protected]
question npm password:
success Logged in.
[3/4] Publishing...
$ rm -fr ./dist & babel ./src --out-dir ./dist -s inline
/bin/sh: 1: babel: not found
error Command failed with exit code 127.
info Visit https://yarnpkg.com/en/docs/cli/publish for documentation about this command.
$