- Overview
- Installing & getting started
- Publishing your package
- Setup local NPM registry
- Configuring prettier
- Available scripts
This boilerplate allows you to create npm package fast and easy with the following setup:
- Storybook to build your component and see it in action before publishing it to npm.
- Rollup to bundle your package.
- Commitizen to simplify professional commit messages.
- standard-version which will bump package version, create a new release tag with the new version and updates CHANGELOG file.
- Install packages
pnpm install
- Package JSON:
- name: add the name of your package.
- description: add the description of your package.
- repository => url: add the URL of your package.
- keywords: add keywords to represent your package (SEO).
- author: add your name.
- bugs => url: add issues link of your repository.
- homepage: add readme link of your repository.
- src/components:
- Add your component with named export in a directory with the same name of your component and don't forget to add index.ts file in the same directory.
- Update
src/components/index.ts
to export your component. - Add component stories in a file with this extension
ComponentName.stories.tsx
following the instructions on storybook site. - Add component test in a file with this extension
ComponentName.test.tsx
.
- run
pnpm storybook
to see your component during development. - run
pnpm commit
to commit your files following conventional commit standards.
- Log into your npm account.
- Click on Edit Profile button.
- Click on Access Tokens.
- Click on Generate New Token:
- Click on Classic Token:
- Enter token name.
- Select Automation if you will use GitHub actions, select Publish if you will publish you package manually.
- Click on Generate Token.
- Copy the generated token and save it somewhere.
- Click on Classic Token:
- Open your repository on GitHub => settings => Secrets and variables => Actions => New repository secret:
- Name: NPM_AUTH_TOKEN
- Secret: paste your npm access token.
- Commit your changes:
pnpm commit
- Create a new release:
NOTE:
pnpm semantic-release
- If you want to commit and run semantic release at the same time use the following script:
pnpm release
- If you want to commit and run semantic release at the same time use the following script:
- push your changes to GitHub to run publish workflow.
- Run your tests:
pnpm test
- Run semantic release script to create a new release, bump package version and update CHANGELOG.md file:
pnpm semantic-release
- Build your package:
pnpm build-lib
- Navigate to lib directory:
cd lib
- Publish your npm package:
npm publish --access public
- I like to publish my package to a local registry and test it locally before publishing it to NPM.
- We will use verdaccio registry:
- Pull verdaccio image:
docker pull verdaccio/verdaccio
- Run verdaccio container:
docker run -it --rm --name verdaccio -p 4873:4873 verdaccio/verdaccio
- Create a new user:
npm adduser --registry http://localhost:4873/
- Publish your package after building it:
npm publish --registry http://localhost:4873/
- Install your package from your local registry:
npm install <package_name> --registry http://localhost:4873/
This build relies on Prettier formatter to enforce code style. And ESLint for identifying problematic patterns found in the code.
-
Setting up prettier:
1- You can find steps on how to set up prettier formatter with WebStorm/PhpStorm here.
Notes:
- It's better to use local
node_modules
version of prettier instead of a global one, to avoid version conflicts (in case the globally installed version does not match the version specified inpackage.json
).
2- Follow the next steps to set up prettier and eslint in VS Code:
-
Install
prettier
plugin -
Install
eslint
plugin -
Open VS Code settings
CTRL + ,
:a- Search for
formatter
=> check Format on saveb- Search for
prettier
=> add.prettierrc
in Prettier: Config Path section && check Prettier: Require Config
3- Please refer to other tutorials if you are using a different IDE.
- It's better to use local
In the project directory, you can run:
- Runs storybook in development mode.
- Opens automatically on http://localhost:6006
- Creates a professional commit following conventional commit standards.
- Creates or updates CHANGELOG file.
- Creates a new release tag.
- Bump package version in
package.json
.
- Runs 2 scripts
pnpm commit
andpnpm semantic-release
.
- Builds your story book for production.
- Builds your package in the
dist
folder in 2 formats:- CommonJS (CJS).
- ECMAScript (ESM).
- Output your package types into
dist/index.d.ts
- Creates a new directory called lib and copies the following into it to make your package ready for publishing:
- dist folder
- package.json
- LICENSE
- README.md
- Runs all test files.
- Runs all unit test files in
/src
directory using watch mode. - Runs all your tests once, then again on every change of your source code.
- Clears test cache.