{"id":17654040,"url":"https://github.com/tomchen/example-typescript-package","last_synced_at":"2025-07-31T17:03:38.357Z","repository":{"id":40769748,"uuid":"324851883","full_name":"tomchen/example-typescript-package","owner":"tomchen","description":"Example TypeScript Package ready to be published on npm \u0026 Tutorial / Instruction / Workflow for 2021","archived":false,"fork":false,"pushed_at":"2021-11-09T10:30:41.000Z","size":596,"stargazers_count":162,"open_issues_count":4,"forks_count":32,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-04T06:08:09.399Z","etag":null,"topics":["boilerplate","example","javascript-library","npm","npm-package","starter","starter-kit","starter-template","typescript","typescript-boilerplate","typescript-example","typescript-library-boilerplate","typescript-packages","typescript-starter"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomchen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-12-27T21:26:59.000Z","updated_at":"2025-06-15T19:00:27.000Z","dependencies_parsed_at":"2022-08-24T05:21:13.541Z","dependency_job_id":null,"html_url":"https://github.com/tomchen/example-typescript-package","commit_stats":null,"previous_names":[],"tags_count":10,"template":true,"template_full_name":null,"purl":"pkg:github/tomchen/example-typescript-package","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomchen%2Fexample-typescript-package","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomchen%2Fexample-typescript-package/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomchen%2Fexample-typescript-package/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomchen%2Fexample-typescript-package/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomchen","download_url":"https://codeload.github.com/tomchen/example-typescript-package/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomchen%2Fexample-typescript-package/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268074161,"owners_count":24191522,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-31T02:00:08.723Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boilerplate","example","javascript-library","npm","npm-package","starter","starter-kit","starter-template","typescript","typescript-boilerplate","typescript-example","typescript-library-boilerplate","typescript-packages","typescript-starter"],"created_at":"2024-10-23T12:08:26.365Z","updated_at":"2025-07-31T17:03:38.301Z","avatar_url":"https://github.com/tomchen.png","language":"TypeScript","readme":"# Example TypeScript Package ready to be published on npm for 2021\n\nThis is an example TypeScript Package ready to be published on npm. It has been set up with automated tests and package publishing workflow using GitHub Actions CI/CD. It is made primarily for GitHub + VS Code (Windows / Mac / Linux) users who are about to write and publish their first TypeScript npm package. This package could serve as a starter / boilerplate / demo for them.\n\n[![npm package](https://img.shields.io/badge/npm%20i-example--typescript--package-brightgreen)](https://www.npmjs.com/package/example-typescript-package) [![version number](https://img.shields.io/npm/v/example-typescript-package?color=green\u0026label=version)](https://github.com/tomchen/example-typescript-package/releases) [![Actions Status](https://github.com/tomchen/example-typescript-package/workflows/Test/badge.svg)](https://github.com/tomchen/example-typescript-package/actions) [![License](https://img.shields.io/github/license/tomchen/example-typescript-package)](https://github.com/tomchen/example-typescript-package/blob/main/LICENSE)\n\nIt uses npm, TypeScript compiler, Jest, webpack, ESLint, Prettier, husky, pinst, commitlint. The production files include CommonJS, ES Modules, UMD version and TypeScript declaration files.\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/\" title=\"Github\"\u003e\u003cimg src=\"https://github.com/get-icon/geticon/raw/master/icons/github-icon.svg\" alt=\"Github\" width=\"21px\" height=\"21px\"\u003e\u003c/a\u003e \u003ca href=\"https://code.visualstudio.com/\" title=\"Visual Studio Code\"\u003e\u003cimg src=\"https://github.com/get-icon/geticon/raw/master/icons/visual-studio-code.svg\" alt=\"Visual Studio Code\" width=\"21px\" height=\"21px\"\u003e\u003c/a\u003e \u003ca href=\"https://www.microsoft.com/windows\" title=\"Windows\"\u003e\u003cimg src=\"https://github.com/get-icon/geticon/raw/master/icons/microsoft-windows.svg\" alt=\"Windows\" width=\"21px\" height=\"21px\"\u003e\u003c/a\u003e \u003ca href=\"https://www.apple.com/macos/\" title=\"Mac OS\"\u003e\u003cimg src=\"https://github.com/get-icon/geticon/raw/master/icons/macOS.svg\" alt=\"Mac OS\" width=\"21px\" height=\"21px\"\u003e\u003c/a\u003e \u003ca href=\"https://www.linuxfoundation.org/\" title=\"Linux\"\u003e\u003cimg src=\"https://github.com/get-icon/geticon/raw/master/icons/linux-tux.svg\" alt=\"Linux\" width=\"21px\" height=\"21px\"\u003e\u003c/a\u003e \u003ca href=\"https://www.npmjs.com/\" title=\"npm\"\u003e\u003cimg src=\"https://github.com/get-icon/geticon/raw/master/icons/npm.svg\" alt=\"npm\" width=\"21px\" height=\"21px\"\u003e\u003c/a\u003e \u003ca href=\"https://www.typescriptlang.org/\" title=\"Typescript\"\u003e\u003cimg src=\"https://github.com/get-icon/geticon/raw/master/icons/typescript-icon.svg\" alt=\"Typescript\" width=\"21px\" height=\"21px\"\u003e\u003c/a\u003e \u003ca href=\"https://jestjs.io/\" title=\"Jest\"\u003e\u003cimg src=\"https://github.com/get-icon/geticon/raw/master/icons/jest.svg\" alt=\"Jest\" width=\"21px\" height=\"21px\"\u003e\u003c/a\u003e \u003ca href=\"https://webpack.js.org/\" title=\"webpack\"\u003e\u003cimg src=\"https://github.com/get-icon/geticon/raw/master/icons/webpack.svg\" alt=\"webpack\" width=\"21px\" height=\"21px\"\u003e\u003c/a\u003e \u003ca href=\"https://eslint.org/\" title=\"ESLint\"\u003e\u003cimg src=\"https://github.com/get-icon/geticon/raw/master/icons/eslint.svg\" alt=\"ESLint\" width=\"21px\" height=\"21px\"\u003e\u003c/a\u003e \u003ca href=\"https://prettier.io/\" title=\"Prettier\"\u003e\u003cimg src=\"https://github.com/get-icon/geticon/raw/master/icons/prettier.svg\" alt=\"Prettier\" width=\"21px\" height=\"21px\"\u003e\u003c/a\u003e \u003ca href=\"https://yarnpkg.com/\" title=\"yarn\"\u003e\u003cimg src=\"https://github.com/get-icon/geticon/raw/master/icons/yarn.svg\" alt=\"yarn\" width=\"21px\" height=\"21px\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Development\n\n### Use as a template\n\n[![Use the template](https://img.shields.io/static/v1?label=\u0026message=Click%20here%20to%20use%20this%20package%20as%20a%20template%20to%20start%20a%20new%20repo%20on%20GitHub\u0026color=brightgreen\u0026style=for-the-badge)](https://github.com/tomchen/example-typescript-package/generate)\n\n(Click the above button to use this example package as a template for your new GitHub repo, this will initialize a new repository and my commits will not be in your git history)\n\n(If you do not use GitHub, you can [download the archive of the example package](https://github.com/tomchen/example-typescript-package/archive/main.zip))\n\n### Set up tools and environment\n\nYou need to have [Node.js](https://nodejs.org/en/download/) installed. Node includes npm as its default package manager.\n\nOpen the whole package folder with a good code editor, preferably [Visual Studio Code](https://code.visualstudio.com/download). Consider installing VS Code extensions [ES Lint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode).\n\nIn the VS Code top menu: **Terminal** -\u003e **New Terminal**\n\n### Install dependencies\n\nInstall dependencies with npm:\n\n```bash\nnpm i\n```\n\n### Write your code\n\nMake necessary changes in **package.json** (name, version, description, keywords, author, homepage and other URLs).\n\nWrite your code in **src** folder, and unit test in **test** folder, replacing the original files there.\n\nThe VS Code shortcuts for formatting of a code file are: \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eAlt\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e (Windows); \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eOption (Alt)\u003c/kbd\u003e + \u003ckbd\u003eF\u003c/kbd\u003e (MacOS); \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eShift\u003c/kbd\u003e + \u003ckbd\u003eI\u003c/kbd\u003e (Linux).\n\nChange code linting and formatting settings in **.prettierrc.js** if you want.\n\n### Test\n\nTest your code with Jest framework:\n\n```bash\nnpm run test\n```\n\n**Note:** Example TypeScript Package uses [husky](https://typicode.github.io/husky/), [pinst](https://github.com/typicode/pinst) and [commitlint](https://commitlint.js.org/) to automatically execute test and [lint commit message](https://www.conventionalcommits.org/) before every commit.\n\n### Build\n\nBuild production (distribution) files in your **dist** folder:\n\n```bash\nnpm run build\n```\n\nIt generates CommonJS (in **dist/cjs** folder), ES Modules (in **dist/esm** folder), bundled and minified UMD (in **dist/umd** folder), as well as TypeScript declaration files (in **dist/types** folder).\n\n### Try it before publishing\n\nRun:\n\n```bash\nnpm link\n```\n\n[npm link](https://docs.npmjs.com/cli/v6/commands/npm-link) will create a symlink in the global folder, which may be **{prefix}/lib/node_modules/example-typescript-package** or **C:\\Users\\\u003cusername\u003e\\AppData\\Roaming\\npm\\node_modules\\example-typescript-package**.\n\nCreate an empty folder elsewhere, you don't even need to `npm init` (to generate **package.json**). Open the folder with VS Code, open a terminal and just run:\n\n```bash\nnpm link example-typescript-package\n```\n\nThis will create a symbolic link from globally-installed example-typescript-package to **node_modules/** of the current folder.\n\nYou can then create a, for example, **testnum.ts** file with the content:\n\n```ts\nimport { Num } from 'example-typescript-package'\nconsole.log(new Num(5).add(new Num(6)).val() === 11)\n```\n\nIf you don't see any linting errors in VS Code, if you put your mouse cursor over `Num` and see its type, then it's all good.\n\nWhenever you want to uninstall the globally-installed example-typescript-package and remove the symlink in the global folder, run:\n\n```bash\nnpm uninstall example-typescript-package -g\n```\n\n### Prepare to publish\n\nCreate an [npm](https://www.npmjs.com/) account.\n\n\u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003eClick to read this section if you do manual publishing\u003c/strong\u003e\u003c/summary\u003e\n\n#### Manual publishing to npm\n\nLog in:\n\n```bash\nnpm adduser\n```\n\nAnd publish:\n\n```bash\nnpm publish\n```\n\n\u003c/details\u003e\n\nThis package is configured to use GitHub Actions CI/CD to automate both the **npm** and **GitHub Packages** publishing process. The following are what you have to do.\n\n#### CI publishing to npm\n\nFollow [npm's official instruction](https://docs.npmjs.com/creating-and-viewing-access-tokens) to create an npm token. Choose \"Publish\" from the website, or use `npm token create` without argument with the CLI.\n\nIf you use 2FA, then make sure it's enabled for **authorization** only instead of **authorization and publishing** (**Edit Profile** -\u003e **Modify 2FA**).\n\nOn the page of your newly created or existing GitHub repo, click **Settings** -\u003e **Secrets** -\u003e **New repository secret**, the **Name** should be `NPM_TOKEN` and the **Value** should be your npm token.\n\n#### CI publishing to GitHub Packages\n\nThe default configuration of this example package **assumes you publish package with an unscoped name to npm**. GitHub Packages must be named with a scope name such as \"@tomchen/example-typescript-package\".\n\nChange `scope: '@tomchen'` to your own scope in **.github/workflows/publish.yml**, also change `addscope` in **package.json**.\n\nIf you publish package with a scoped name to npm, change the name to something like \"@tomchen/example-typescript-package\" in **package.json**, and remove the `- run: npm run addscope` line in **.github/workflows/publish.yml**\n\nIf you publish your package to npm only, and don't want to publish to GitHub Packages, then delete the lines from `- name: Setup .npmrc file to publish to GitHub Packages` to the end of the file in **.github/workflows/publish.yml**.\n\n(You might have noticed `secret.GITHUB_TOKEN` in **.github/workflows/publish.yml**. You don't need to set up a secret named `GITHUB_TOKEN` actually, it is [automatically created](https://docs.github.com/en/free-pro-team@latest/actions/reference/authentication-in-a-workflow#about-the-github_token-secret))\n\n### Publish\n\nNow everything is set. The example package has automated tests and upload (publishing) already set up with GitHub Actions:\n\n- Every time you `git push` or a pull request is submitted on your `master` or `main` branch, the package is automatically tested against the desired OS and Node.js versions with GitHub Actions.\n- Every time an [**annotated**](https://git-scm.com/book/en/v2/Git-Basics-Tagging#_annotated_tags) (not [lightweight](https://git-scm.com/book/en/v2/Git-Basics-Tagging#_lightweight_tags)) \"v*\" tag is pushed onto GitHub, a GitHub release is automatically generated from this version, it also automatically publishes to the npm registry and/or GitHub Packages registry to update the package there.\n  - [`npm version`](https://docs.npmjs.com/cli/version/) / [`yarn version`](https://yarnpkg.com/cli/version) is useful to create tags.\n  - (npm or yarn v1, not yarn v2) You could also add `\"postversion\": \"git push --follow-tags\"` to **package.json** file to push it automatically after `npm` or `yarn` `version`.\n  - (yarn v1, not v2) because `yarn version` doesn't check whether there are uncommitted changes, you can add `\"preversion\": \"git diff-index --quiet HEAD --\"` to **package.json**\n    - Note: `preversion`, `postversion` doesn't work in yarn v2\n\nFor npm registry: you can unpublish a version or the whole package but can never re-publish the same version under the same name.\n\nIf you want to modify the description / README on the npm package page, you have to publish a new version. You can modify the description on GitHub Packages without publishing.\n\n## Notes\n\n- It uses npm but you can easily switch to yarn, of course (remember to change all \"npm\" in `scripts` in the file **package.json**)\n  - Whether you use npm as your package manager ≠ Whether you can publish to the npm registry\n- Works fine in VS Code. In my configuration **.eslintrc** and **.prettierrc** cooperate perfectly\n- See `scripts` in **package.json** for other predefined script commands\n- [pinst](https://github.com/typicode/pinst) is used to solve [a problem of husky](https://typicode.github.io/husky/#/?id=yarn-2)\n- The installation of the package with npm, yarn v1 and yarn v2+ is ensured in [this test](https://github.com/tomchen/example-typescript-package-test)\n\n## References\n\n- [Creating and publishing unscoped public packages - npm docs](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages)\n- [npm-publish - npm docs](https://docs.npmjs.com/cli/v6/commands/npm-publish)\n- [Publishing - TypeScript docs](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html)\n- [Publishing Node.js packages - GitHub Docs](https://docs.github.com/en/free-pro-team@latest/actions/guides/publishing-nodejs-packages)\n\nBtw, if you want to publish Python package, go to [Example PyPI (Python Package Index) Package \u0026 Tutorial / Instruction / Workflow for 2021](https://github.com/tomchen/example_pypi_package).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomchen%2Fexample-typescript-package","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomchen%2Fexample-typescript-package","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomchen%2Fexample-typescript-package/lists"}