The starter template that built on top of Vite and designed for creating production ready NPM libraries in TypeScript
- Uses
npm
,npx
andnvm
cli tools - Generates UMD/CJS and ESM modules
- Generates TypeScript type definitions
- React support
- Preconfigured GitHub Actions CI/CD
- Automated version and release management
- Preconfigured code formatters, linters, test framework and build tools
- Automated generation of changelog and release notes
- Automated generation of GitHub Pages with Storybook, Docusaurus, Typedoc and Test Coverage report
- Generates ES6 compatible module format (for modern browsers)
- Stylelint is not used
- Browserslist is not used
- Does not generates sourcemaps
- Does not bundles declaration files into a single
.d.ts
file (Vite bundler issue) - Does not strip whitespaces and new lines from ESM bundle (Vite bundler issue)
- Default code coverage is set to 80% minimum
- Edit
.npmrc
file to whitelist npm audit issues
Name | Description | Links |
---|---|---|
Vite | Build tool | https://vitejs.dev |
Vitest | Test framework | https://vitest.dev |
Storybook | A tool that helps you create React components in isolation | https://storybook.js.org |
TypeScript | Type linter | https://www.typescriptlang.org |
Editorconfig | A set of configuration rules that define coding style preferences | https://editorconfig.org |
Prettier | Code formatter | https://prettier.io |
ESLint | Code linter. The basic configuration is based on the airbnb configuration. | https://eslint.org https://github.com/airbnb/javascript |
Husky | Runs custom cli commands on git hook events | https://typicode.github.io/husky |
Lint-staged | Runs linters against staged git files | https://www.npmjs.com/package/lint-staged |
Semantic-release | Automates package versioning, releasing, publishing packages to npm and uploading static UI to Github pages | https://semantic-release.gitbook.io/semantic-release/usage/configuration |
Commitlint | Lints git commit messages | https://commitlint.js.org https://www.conventionalcommits.org/en/v1.0.0 |
Commitizen | Interactive cli tool for creating semantically correct commit messages | https://commitizen-tools.github.io/commitizen |
GitHub actions CI/CD | Preconfigured GitHub Actions workflow | https://docs.github.com/en/actions |
Import alias | Preconfigured import alias #src/* -> ./src/* |
https://vitejs.dev/config/shared-options.html#resolve-alias https://www.typescriptlang.org/tsconfig#paths https://www.npmjs.com/package/eslint-import-resolver-alias |
Typedoc | Api documentation generator from TSdoc comments | https://typedoc.org https://tsdoc.org |
Docusaurus | Documentation UI generator | https://docusaurus.io |
React Testing Library | Solution for testing React components | https://testing-library.com/docs/react-testing-library/intro https://www.npmjs.com/package/@testing-library/jest-dom |
Command | Description | Notes |
---|---|---|
build |
Lint TS types and build library | dist directory will contain UMD/CJS, ESM and TS types declarations |
test |
Run tests | |
test:watch |
Run tests in watch node | |
test:coverage |
Generate code coverage report | coverage directory will contain code coverage reports |
test:dashboard |
Run tests in watch node with UI dashboard | Automatically opens http://localhost:51204/__vitest__/# page in the browser. See documentation at https://vitest.dev/guide/ui.html |
lint |
Lint all .ts and .tsx files located in src directory using eslint |
ESLint configuration files: .eslintrc.cjs and .eslintignore |
lint:fix |
Lint and fix all .ts and .tsx files located in src directory using eslint |
|
format |
Check formatting of all .ts , .tsx and .json files located in src directory using prettier |
Prettier configuration file: .prettierrc.cjs |
format:fix |
Reformat all .ts , .tsx and .json files located in src directory using prettier |
Files can be modified |
prepare |
Husky integration-related command. No need to invoke it manually. | Automatically invoked by npm install command |
commit |
Trigger interactive cli tool for creating semantically correct commit messages | Runs Commitizen. Use this command instead of git commit |
storybook |
Start Storybook | |
build:storybook |
Build Storybook static UI | Generated files will be located in storybook-static directory |
docusaurus |
Start Docusaurus UI | Docusaurus directory: docusaurus |
build:docusaurus |
Build Docusaurus static UI | Generated files will be located in docusaurus/build directory |
build:typedoc |
Build api documentation static UI | Generated files will be located in typedoc directory |
security-audit:prod |
Start npm audit for production packages | Used by GitHub Actions workflow .github/workflows/release.yml |
security-audit:dev |
Start npm audit for devevelopment packages | Used by GitHub Actions workflow .github/workflows/release.yml |
# Clone the GitHub project
git clone https://github.com/gavrya/ts-react-vite-npm-lib-template.git my-new-repo
# Navigate into the cloned directory
cd my-new-repo
# Remove the .git directory
rm -rf .git
# Initialize a new Git repository
git init
# Set correct node version using nvm
nvm use
# Install packages
npm install
- Change
version
to initial version 0.0.1 - Change
name
to your git repo name - Edit
description
- Change
private
totrue
when you will be ready to publish your package to the npm - Edit
license
- Edit
keywords
- Change
repository.url
using templatehttps://github.com/{git_user}/{git_repo_name}.git
- Change
homepage
using templatehttps://{git_user}.github.io/{git_repo_name}/docs
- Change
build.name
fromTsReactViteNpmLibTemplate
to your library name in capitalized case - Set global names of external libraries
build.rollupOptions.output.globals
- Update code coverage limits
test.coverage
- Edit
config
fields:title
,tagline
,favicon
,organizationName
,projectName
- Edit
themeConfig
fields:navbar.title
,navbar.logo
,footer.copyright
- Add a meaningful description associated with your library
- Add instructions for installing your library
- Add instructions for using your library
YT video tutorial: https://youtu.be/QZdY4XYbqLI?t=411
- Create
NPM_TOKEN
- Create
GH_TOKEN
https://github.com/settings/tokens/new?scopes=repo
- Create an empty
gh-pages
repository
# Create a new branch called gh-pages that is completely empty.
# It doesn't contain any files or commit history from the previous branch you were on.
git checkout --orphan gh-pages
# This command creates a commit in the gh-pages branch with the specified commit message.
# The commit itself doesn't introduce any changes to the branch because it's empty.
# However, this initial commit is often used as a placeholder to initialize the branch.
git commit --allow-empty -m "chore: init"
# This command pushes the local gh-pages branch, including the empty commit you created earlier, to the remote repository named origin.
# As a result, the remote repository now has a branch called gh-pages with the empty commit, and you can use this branch to publish content or set up a GitHub Pages site.
git push origin gh-pages
- Setup GitHub pages
GitHub Pages static UI routes:
/docs
- Docusaurus
/coverage
- Test Coverage
/storybook-static
- Storybook
/typedoc
- Typedoc
# Add your files and commit them
git add .
git commit -m "chore: init"
# Create a new empty repository on GitHub (assuming it's named 'my-new-repo')
# Copy the URL of the new repository (should be something like https://github.com/username/my-new-repo.git)
# Add the new remote origin
git remote add origin https://github.com/username/my-new-repo.git
# Verify the new remote
git remote -v
# Push your commits to the new remote origin
git push -u origin master