[LIBRARY TYPESCRIPT-REACT TEMPLATE]

Introduction

A template to build TypeScript libraries with both Vanilla JavaScript and React entry points.

The goal of this template is to simplify the process of creating, maintaining, and publishing libraries. It provides a ready-to-use setup with sensible defaults, including an automated release workflow triggered on every push to the repository.

Usage

Using this library is straightforward:

1. Create a repository

Click the Use this template button to create a new repository based on this template.

2. Configure npm authentication

Create an NPM_TOKEN repository secret in your new repository. The token must be a valid npm access token with read and write permissions. On top of that, it must bypass 2FA, as it is used in a CD workflow.

[!NOTE] Follow GitHub’s guide to create repository secrets.

[!NOTE] This token is required by the automated release workflow.

3. Update package.json

Edit the package.json file to reflect your library’s metadata:

• name – Your library name
• version – Start at 0.0.0
• description – Short and meaningful description
• repository – Repository URL
• author – Author information
• bugs – Issue tracker URL
• homepage – Project homepage (e.g. the README.md link)
• keywords – Relevant keywords for discoverability

4. Install dependencies and start development

Execute the following commands:

npm install
npm run dev

5. Develop your library

This template comes with sample code inside the src folder.

The only important thing to notice is that every feature your library wants to export should be defined inside src/core/index.ts and src/react/index.ts.

[!NOTE] src/core/index.ts and src/react/index.ts are defined as the entry points of your library.

On top of that, every commit must follow this Conventional Commits format:

<type>(<scope>): <description> [<issue-number>]

[!NOTE] This is required by the release workflow, which analyzes every commit to automatically generate the releases.

6. Validate locally using the dev site

This template includes a local development site under the dev folder.

Remove the dependencies from the package.json, and execute npm install ../. This will install the local library.

Update the sample code and visit http://localhost:5173/dev/ to check the implementation.

7. Build a demo site

A sample Next.js demo site is included in the www folder.

[!NOTE] There is a GitHub Action that deploys it on every push.

To begin with, update the basePath setting inside the next.config.ts. It should match your repository slug (e.g. /my-repo-name/).

Then, you can update the sample code and visit http://localhost:3000/my-repo-name to check the implementation.

Finally, remember to enable GitHub Pages with GitHub Actions for your repository.

8. Finalize documentation

Update the README.md to describe your library’s purpose and usage.

[!IMPORTANT] Don’t forget to update the release badge URL at the top of this file if you keep it — it currently points to this repository.

[!NOTE] To gain a deeper understanding of how to use this library and how it works under the hood, visit the wiki page.

[!NOTE] At the time of writing, it seems npm does not support fine-grained tokens for CD workflows. A recommended workaround is to publish the package once. For instance, using the CLI: npm login and npm publish. Then, create a token restricted to that specific package.

[!NOTE] There is a ticket to add testing tools to improve the library's validation workflow.

Changelog

Detailed changes for each release are documented in CHANGELOG.md.

License

This work is published under MIT License.

Author

Always happy to receive a greeting on:

• LinkedIn
• Web