MonkeySpan

About

An example of how to make a React component package. 🐒

Tinker with this component in Storybook.

See this package in action in this CodeSandbox. 🏜

Tooling

• Babel
• ESLint
• gh cli
• GitHub Actions
• Husky
• Jest
• lint-staged
• PostCSS
• Prettier
• Rollup
• Storybook
• Stylelint
• @testing-library
• TypeScript

Usage

import { MonkeySpan } from "monkeyspan";

function App() {
  return (
    <div>
      <MonkeySpan label="a monkey emoji">🐵</MonkeySpan>
    </div>
  );
}

export default App;

Contributing

Please note that this project follows the practices of Semantic Versioning and maintaining a CHANGELOG.

Making Changes

1. Ensure you have the necessary dependencies installed:

   npm install

2. Make your changes

3. Test them in Storybook and/or using a separate app (e.g npx create-react-app demo):

   If you want to test your changes in a separate app, Yalc is a fantastic tool for linking purposes.

   # in this project's root directory, run
   yalc publish
   
   # then in the root directory of the app you're using to demo this package, run:
   yalc add monkeyspan && npm run start

   You should now be able to use the package in that app, e.g.

   import { MonkeySpan } from "monkeyspan";

4. Make sure your changes haven't broken anything:

   Run the tests and linting.

   npm run test

   Ensure the build will generate successfully.

   npm run build

5. Commit your changes, open a pull request (npm run pr:create), and merge them to the main branch.

6. See Publishing Releases.

Available Scripts

Command	Params	Example	Purpose
build	none	npm run build	Runs npm run build:types && npm run build:rollup
build:link	none	npm run build:link	Generates a production build, then publishes it locally via yalc, and copies to your clipboard the command to run to complete the link within an app directory via `npm run build && npx yalc publish && echo "yalc add monkeyspan"
build:storybook	none	npm run build:storybook	Generates a build for storybook using build-storybook.
build:storybook:docs	none	npm run build:storybook:docs	Generates a build for storybook docs using build-storybook --docs.
build:rollup	none	npm run build:rollup	Generates a build and source map (./dist/bundle.js, ./dist/bundle.es.js & ./dist/bundle.js.map) using Rollup & Babel.
build:types	none	npm run build:types	Runs npx tsc --project ./tsconfig.build.json --emitDeclarationOnly, which runs the typescript compiler to generate types files.
clean	none	npm run clean	Runs npm run clean:eslint && npm run clean:css && npm run clean:prettier
clean:artifacts	none	npm run clean:artifacts	Runs rm -rv ./dist ; rm -rv .babel-config-test ; rm -rv storybook-static, which attempts to delete artifacts created by other scripts.
clean:css	none	npm run clean:css	Runs npx stylelint 'src/**/*.css' --fix, which attempts to resolve all stylelint issues in the project.
clean:eslint	none	npm run clean:eslint	Runs npx eslint --fix ., which attempts to resolve all eslint issues in the project.
clean:prettier	none	npm run clean:prettier	Runs npx prettier --write ., which attempts to resolve all prettier issues in the project.
pr:create	none	gh pr create --web --fill	Pushes your branch up, opens your browser at the create PR page for your branch, and fills in commit log info automatically.
storybook	none	npm run storybook	Starts storybook on port 6006 via start-storybook -p 6006.
storybook:docs	none	npm run storybook:docs	Starts storybook on port 6006 in docs mode via start-storybook -p 6006 --docs.
storybook:nocache	none	npm run storybook:nocache	Starts storybook on port 6006 without manager caching via start-storybook -p 6006 --no-manager-cache.
tag	--value	npm run tag --value=1.2.3	Runs npm run tag:create --value=<value> and npm run tag:release --value=<value>
tag:create	--value	npm run tag:create --value=1.2.3	Runs npx json -I -f ./package.json -e 'this.version=\"$npm_config_value\"' && npm i && git ci -am \"$npm_config_value\" && git tag $npm_config_value, which updates the package.json version to the value provided, updates the package-lock.json, generates a commit for the changes, and tags the commit using the value provided.
tag:release	--value	npm run tag:release --value=1.2.3	Runs git push origin $npm_config_value && gh release create $npm_config_value --title $npm_config_value --notes-file ./CHANGELOG.md, which pushes the tag value provided to GitHub, then produces a release for it using the gh cli. You will need the gh cli for this command to work.
test	none	npm run test	Runs npm run test:eslint && npm run test:css && npm run test:prettier && npm run test:types && npm run test:code
test:babel	none	npm run test:babel	Runs npx babel src/ --out-dir .babel-config-test --extensions ".ts,.tsx,.js,.jsx", providing a glimpse at how babel's current config transforms the src code. Find the output in .babel-config-test/.
test:code	none	npm run test:code	Runs the test suite via npx jest.
test:css	none	npm run test:css	Runs stylelint suite via npx stylelint 'src/**/*.css'.
test:eslint	none	npm run test:eslint	Runs npx eslint ., providing info about issues.
test:prettier	none	npm run test:prettier	Runs npx prettier --check ., providing info about issues.
test:types	none	npm run test:types	Runs npx tsc --project ./tsconfig.eslint.json --noEmit, which checks for typescript errors without emitting any files.

Publishing Releases

Please note that the following should be done on the main branch, except for under certain circumstances, e.g. patching an older version than the last.

In order to generate a release, you need to produce a new package version and a corresponding tag for said version.

For example, let's say you want to add a component or feature to this package.

To do so, you'd simply follow the instructions in Making Changes, then produce your version via:

1. Determine what type of changes you've made per Semantic Versioning to identify what the next version for this package will be. Check the package.json's current version to begin.

2. Add an entry to the CHANGELOG.

3. Run the following command with your new version in place of <VERSION>:

   npm run tag --value=<VERSION>

   If it was successful, you'll get a link like https://github.com/tonytino/monkeyspan/releases/tag/<VERSION> at the end of output.

4. Go to the URL provided by the script output to see your new release in GitHub.

5. Go to the Actions tab for this project and you should see a job running for your release, which, if successful, will upload your new version of this package to npm.