Vite TypeScript NPM Package

Scaffold TypeScript npm packages using this template to bootstrap your next library.

Tip

Looking for a JavaScript version of this template? Try: Vite JavaScript NPM Package

Or, try a tsup version of this template: tsup NPM Package

Getting Started

Begin via any of the following:

• Press the "Use this template" button

• Use GitHub CLI to execute:

  gh repo create <name> --template="https://github.com/jasonsturges/vite-typescript-npm-package"
  

• Simply git clone, delete the existing .git folder, and initialize a fresh repo:

  git clone https://github.com/jasonsturges/vite-typescript-npm-package.git
  cd vite-typescript-npm-package
  rm -rf .git
  git init
  git add -A
  git commit -m "Initial commit"
  

Remember to use npm search <term> to avoid naming conflicts in the NPM Registery for your new package name.

Usage

The following tasks are available:

• dev: Run Vite in watch mode to detect changes - all modules are compiled to the dist/ folder, as well as rollup of all types to a d.ts declaration file
• start: Run Vite in host mode to work in a local development environment within this package - vite hosts the index.html with real time HMR updates
• build: Run Vite to build a production release distributable
• build:types: Run DTS Generator to build d.ts type declarations only

Rollup all your exports to the top-level index.ts for inclusion into the build distributable.

For example, if you have a utils/ folder that contains an arrayUtils.ts file.

/src/utils/arrayUtils.ts:

export const distinct = <T>(array: T[] = []) => [...new Set(array)];

Include that export in the top-level index.ts .

/src/index.ts:

// Main library exports - these are packaged in your distributable
export { distinct } from "./utils/arrayUtils"

Development

There are multiple strategies for development, either working directly from the library or from a linked project.

Local Development

Vite features a host mode for development with real time HMR updates directly from the library via the start script. This enables rapid development within the library instead of linking from other projects.

Using the start task, Vite hosts the index.html for a local development environment. This file is not included in the production build. Note that only exports specified from the index.ts are ultimately bundled into the library.

As an example, this template includes a React app, which could be replaced with a different framework such as Vue, Solid.js, Svelte, etc...

For UI projects, you may want to consider adding tools such as Storybook to isolate UI component development by running a storybook script from this package.

Project Development

To use this library with other app projects before submitting to a registry such as NPM, either link or pack to test.

Using Link

Run the dev script and link packages.

Using the dev task, Vite detects changes and compiles all modules to the dist/ folder, as well as rollup of all types to a d.ts declaration file.

To test your library from within an app:

• From this library: run npm link or yarn link command to register the package
• From your app: run npm link "mylib" or yarn link "mylib" command to use the library inside your app during development

Inside your app's node_modules/ folder, a symlink is created to the library.

Using Pack

From you library, pack it to create a tarball:

npm pack

This will create a [name].tgz tarball that includes the result of what will be uploaded to npm.

Install the pack file in a test app:

npm install [name].tgz

Development Cleanup

Once development completes, unlink both your library and test app projects.

• From your app: run npm unlink "mylib" or yarn unlink "mylib" command to remove the library symlink
• From your library: run npm unlink or yarn unlink command to unregister the package

If you mistakenly forget to unlink, you can manually clean up artifacts from yarn or npm.

For yarn, the link command creates symlinks which can be deleted from your home directory:

~/.config/yarn/link

For npm, the link command creates global packages which can be removed by executing:

sudo npm rm --global "mylib"

Confirm your npm global packages with the command:

npm ls --global --depth 0

For your app, simply reinstall dependencies to clear any forgotten linked packages. This will remove any symlinks in the node_modules/ folder.

Release Publishing

Update your package.json to the next version number and tag a release.

Assure that your package lockfile is also updated by running an install. For npm, this will assure the lockfile has the updated version number. Yarn does not duplicate the version number in the lockfile.

Assure either a .npmrc or publishConfig in your package.json:

package.json:

  "publishConfig": {
    "registry": "https://registry.npmjs.org/",
    "scope": "username"
    "access": "public",
  }

If you are publishing to a private registry such as GitHub packages, update your package.json to include publishConfig and repository:

package.json:

  "publishConfig": {
    "registry": "https://npm.pkg.github.com/@MyOrg"
  }

Unless you are using a continuous integration service such as GitHub Actions, assure that your dist/ folder is cleanly build. Note that npm publish will ship anything inside the distributable folder.

For clean builds, you may want to install the rimraf package and add a clean or prebuild script to your package.json to remove any artifacts from your dist/ folder. Or, manually delete the dist/ folder yourself.

package.json:

  "scripts": {
    "clean": "rimraf dist"
  }

Before you submit for the first time, make sure your package name is available by using npm search. If npm rejects your package name, update your package.json and resubmit.

npm search <term>

Once ready to submit your package to the NPM Registry, execute the following tasks via npm (or yarn):

npm run build

Assure the proper npm login:

npm login

Submit your package to the registry:

npm publish --access public

Continuous Integration

For continuous integration with GitHub Actions, create a .github/workflows/publish.yml

For public NPM packages, use the following workflow:

name: Publish Package to npmjs
on:
  release:
    types: [created]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm run build
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

For private GitHub packages, use the following workflow:

name: Publish Package to GitHub Packages
on:
  release:
    types: [created]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: "https://registry.npmjs.org"
          scope: "@MyOrg"
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - run: npm ci
      - run: npm run build
      - run: npm publish

This will deploy your build artifact when a release is tagged.

Obtain an "Automation" CI/CD access token to bypass 2FA from npm by selecting your profile image in the upper right, and chosing "Access Tokens".

To add secrets to your repository:

• From your repository, select Settings
• From the Security section of the sidebar, expand Secrets and variables and select Actions
• From the Secrets tab, press New repository secret to add the NPM_TOKEN key

To add secrets to your organization:

• From your organization, select Settings
• From the Security section of the sidebar, expand Secrets and variables and select Actions
• From the Secrets tab, press New organization secret to add the NPM_TOKEN key

For more information, see:

• Using secrets in GitHub Actions
• Publish to npmjs and GPR with npm