You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This 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<a href="https://github.com/" title="Github"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/github-icon.svg" alt="Github" width="21px" height="21px"></a> + VS Code<a href="https://code.visualstudio.com/" title="Visual Studio Code"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/visual-studio-code.svg" alt="Visual Studio Code" width="21px" height="21px"></a> (Windows<a href="https://www.microsoft.com/windows" title="Windows"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/microsoft-windows.svg" alt="Windows" width="21px" height="21px"></a> / Mac<a href="https://www.apple.com/macos/" title="Mac OS"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/macOS.svg" alt="Mac OS" width="21px" height="21px"></a> / Linux<a href="https://www.linuxfoundation.org/" title="Linux"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/linux-tux.svg" alt="Linux" width="21px" height="21px"></a>) users who are about to write and publish their first TypeScript npm package. This package could serve as a starter / boilerplate / demo for them.
4
4
5
-
This 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<a href="https://github.com/" title="Github"><img src="https://github.com/tomchen/stack-icons/blob/master/logos/github-icon.svg" alt="Github" width="21px" height="21px"></a> + VS Code<a href="https://code.visualstudio.com/" title="Visual Studio Code"><img src="https://github.com/tomchen/stack-icons/blob/master/logos/visual-studio-code.svg" alt="Visual Studio Code" width="21px" height="21px"></a> (Windows<a href="https://www.microsoft.com/windows" title="Windows"><img src="https://github.com/tomchen/stack-icons/blob/master/logos/microsoft-windows.svg" alt="Windows" width="21px" height="21px"></a> / Mac<a href="https://www.apple.com/macos/" title="Mac OS"><img src="https://github.com/tomchen/stack-icons/blob/master/logos/macOS.svg" alt="Mac OS" width="21px" height="21px"></a> / Linux<a href="https://www.linuxfoundation.org/" title="Linux"><img src="https://github.com/tomchen/stack-icons/blob/master/logos/linux-tux.svg" alt="Linux" width="21px" height="21px"></a>) users who are about to write and publish their first TypeScript npm package. This package could serve as a starter / boilerplate / demo for them.
The production files include CommonJS, ES Modules, UMD version and TypeScript declaration files.
7
+
It uses npm<a href="https://www.npmjs.com/" title="npm"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/npm.svg" alt="npm" width="21px" height="21px"></a>, TypeScript compiler<a href="https://www.typescriptlang.org/" title="Typescript"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/typescript-icon.svg" alt="Typescript" width="21px" height="21px"></a>, Jest<a href="https://jestjs.io/" title="Jest"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/jest.svg" alt="Jest" width="21px" height="21px"></a>, webpack<a href="https://webpack.js.org/" title="webpack"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/webpack.svg" alt="webpack" width="21px" height="21px"></a>, ESLint<a href="https://eslint.org/" title="ESLint"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/eslint.svg" alt="ESLint" width="21px" height="21px"></a>, Prettier<a href="https://prettier.io/" title="Prettier"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/prettier.svg" alt="Prettier" width="21px" height="21px"></a>. The production files include CommonJS, ES Modules, UMD version and TypeScript declaration files.
10
8
11
9
## Development
12
10
11
+
### Use as a template
12
+
13
+
[](https://github.com/tomchen/example-typescript-package/generate)
14
+
15
+
(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)
16
+
17
+
(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))
18
+
19
+
### Set up tools and environment
20
+
13
21
You need to have [Node.js](https://nodejs.org/en/download/) installed. Node includes npm as its default package manager.
14
22
15
23
Open 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).
@@ -85,11 +93,13 @@ Whenever you want to uninstall the globally-installed example-typescript-package
85
93
npm uninstall example-typescript-package -g
86
94
```
87
95
88
-
### Publish
96
+
### Prepare to publish
89
97
90
98
Create an [npm](https://www.npmjs.com/) account.
91
99
92
-
#### Manual Publishing
100
+
<details><summary><strong>Click to read this section if you do manual publishing</strong></summary>
101
+
102
+
#### Manual publishing to npm
93
103
94
104
Log in:
95
105
@@ -103,22 +113,47 @@ And publish:
103
113
npm publish
104
114
```
105
115
106
-
#### CI Publishing
116
+
</details>
117
+
118
+
This 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.
107
119
108
-
This package is configured to use GitHub Actions CI/CD to automate the npm publishing process. The following are what you have to do.
120
+
#### CI publishing to npm
109
121
110
122
Follow [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.
111
123
112
124
If you use 2FA, then make sure it's enabled for **authorization** only instead of **authorization and publishing** (**Edit Profile** -> **Modify 2FA**).
113
125
114
126
On the page of your newly created or existing GitHub repo, click **Settings** -> **Secrets** -> **New repository secret**, the **Name** should be `NPM_TOKEN` and the **Value** should be your npm token.
115
127
128
+
#### CI publishing to GitHub Packages
129
+
130
+
The 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".
131
+
132
+
Change `scope: '@tomchen'` to your own scope in **.github/workflows/test.yml**, also change `addscope` in **package.json**.
133
+
134
+
If 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/test.yml**
135
+
136
+
If 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/test.yml**.
137
+
138
+
(You might have noticed `secret.GITHUB_TOKEN` in **.github/workflows/test.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))
139
+
140
+
### Publish
141
+
142
+
Now everything is set. The example package has automated tests and upload (publishing) already set up with GitHub Actions:
143
+
144
+
- Every time you `git push` your `master` or `main` branch, the package is automatically tested against the desired OS and Node.js versions with GitHub Actions.
145
+
- Every time a new release (either the initial version or an updated version) is created, the latest version of the package is automatically published to npm and/or GitHub Packages registry with GitHub Actions.
146
+
147
+
Apparently, you have to change the version number in order to publish a new version to the registries. You can unpublish a version or the whole package but can never re-publish the same version under the same name.
148
+
149
+
If you want to modify the description / README on the npm package page, you have to publish a new version.
150
+
116
151
## Notes
117
152
118
153
- It uses npm but you can easily switch to yarn, of course (remember to change all "npm" in `scripts` in the file **package.json**)
119
154
- Whether you use npm as your package manager ≠ Whether you can publish to the npm registry
120
155
- Works fine in VS Code. In my configuration **.eslintrc** and **.prettierrc** cooperate perfectly
121
-
- See `scripts`.`build` in **package.json** for other predefined script commands
156
+
- See `scripts` in **package.json** for other predefined script commands
0 commit comments