|
1 | | -# Example TypeScript Package ready to be published on npm for 2021 |
2 | | - |
3 | | -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 + 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. |
4 | | - |
5 | | -[](https://www.npmjs.com/package/example-typescript-package) [](https://github.com/tomchen/example-typescript-package/releases) [](https://github.com/tomchen/example-typescript-package/actions) [](https://github.com/tomchen/example-typescript-package/blob/main/LICENSE) |
6 | | - |
7 | | -It uses npm, TypeScript compiler, Jest, webpack, ESLint, Prettier, husky, pinst, commitlint. The production files include CommonJS, ES Modules, UMD version and TypeScript declaration files. |
8 | | - |
9 | | -<p align="center"> |
10 | | -<a href="https://github.com/" title="Github"><img src="https://github.com/get-icon/geticon/raw/master/icons/github-icon.svg" alt="Github" width="21px" height="21px"></a> <a href="https://code.visualstudio.com/" title="Visual Studio Code"><img src="https://github.com/get-icon/geticon/raw/master/icons/visual-studio-code.svg" alt="Visual Studio Code" width="21px" height="21px"></a> <a href="https://www.microsoft.com/windows" title="Windows"><img src="https://github.com/get-icon/geticon/raw/master/icons/microsoft-windows.svg" alt="Windows" width="21px" height="21px"></a> <a href="https://www.apple.com/macos/" title="Mac OS"><img src="https://github.com/get-icon/geticon/raw/master/icons/macOS.svg" alt="Mac OS" width="21px" height="21px"></a> <a href="https://www.linuxfoundation.org/" title="Linux"><img src="https://github.com/get-icon/geticon/raw/master/icons/linux-tux.svg" alt="Linux" width="21px" height="21px"></a> <a href="https://www.npmjs.com/" title="npm"><img src="https://github.com/get-icon/geticon/raw/master/icons/npm.svg" alt="npm" width="21px" height="21px"></a> <a href="https://www.typescriptlang.org/" title="Typescript"><img src="https://github.com/get-icon/geticon/raw/master/icons/typescript-icon.svg" alt="Typescript" width="21px" height="21px"></a> <a href="https://jestjs.io/" title="Jest"><img src="https://github.com/get-icon/geticon/raw/master/icons/jest.svg" alt="Jest" width="21px" height="21px"></a> <a href="https://webpack.js.org/" title="webpack"><img src="https://github.com/get-icon/geticon/raw/master/icons/webpack.svg" alt="webpack" width="21px" height="21px"></a> <a href="https://eslint.org/" title="ESLint"><img src="https://github.com/get-icon/geticon/raw/master/icons/eslint.svg" alt="ESLint" width="21px" height="21px"></a> <a href="https://prettier.io/" title="Prettier"><img src="https://github.com/get-icon/geticon/raw/master/icons/prettier.svg" alt="Prettier" width="21px" height="21px"></a> <a href="https://yarnpkg.com/" title="yarn"><img src="https://github.com/get-icon/geticon/raw/master/icons/yarn.svg" alt="yarn" width="21px" height="21px"></a> |
11 | | -</p> |
12 | | - |
13 | | -## Development |
14 | | - |
15 | | -### Use as a template |
16 | | - |
17 | | -[](https://github.com/tomchen/example-typescript-package/generate) |
18 | | - |
19 | | -(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) |
20 | | - |
21 | | -(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)) |
22 | | - |
23 | | -### Set up tools and environment |
24 | | - |
25 | | -You need to have [Node.js](https://nodejs.org/en/download/) installed. Node includes npm as its default package manager. |
26 | | - |
27 | | -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). |
28 | | - |
29 | | -In the VS Code top menu: **Terminal** -> **New Terminal** |
30 | | - |
31 | | -### Install dependencies |
32 | | - |
33 | | -Install dependencies with npm: |
| 1 | +# NiftyKit DropKit.js |
34 | 2 |
|
| 3 | +## Installation |
| 4 | +1. Install via npm |
35 | 5 | ```bash |
36 | | -npm i |
| 6 | +$ npm install dropkit.js |
37 | 7 | ``` |
38 | 8 |
|
39 | | -### Write your code |
40 | | - |
41 | | -Make necessary changes in **package.json** (name, version, description, keywords, author, homepage and other URLs). |
42 | | - |
43 | | -Write your code in **src** folder, and unit test in **test** folder, replacing the original files there. |
44 | | - |
45 | | -The VS Code shortcuts for formatting of a code file are: <kbd>Shift</kbd> + <kbd>Alt</kbd> + <kbd>F</kbd> (Windows); <kbd>Shift</kbd> + <kbd>Option (Alt)</kbd> + <kbd>F</kbd> (MacOS); <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>I</kbd> (Linux). |
46 | | - |
47 | | -Change code linting and formatting settings in **.prettierrc.js** if you want. |
48 | | - |
49 | | -### Test |
50 | | - |
51 | | -Test your code with Jest framework: |
52 | | - |
53 | | -```bash |
54 | | -npm run test |
55 | | -``` |
56 | | - |
57 | | -**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. |
58 | | - |
59 | | -### Build |
60 | | - |
61 | | -Build production (distribution) files in your **dist** folder: |
62 | | - |
63 | | -```bash |
64 | | -npm run build |
65 | | -``` |
66 | | - |
67 | | -It 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). |
68 | | - |
69 | | -### Try it before publishing |
70 | | - |
71 | | -Run: |
72 | | - |
73 | | -```bash |
74 | | -npm link |
75 | | -``` |
76 | | - |
77 | | -[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\<username>\AppData\Roaming\npm\node_modules\example-typescript-package**. |
78 | | - |
79 | | -Create 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: |
80 | | - |
81 | | -```bash |
82 | | -npm link example-typescript-package |
| 9 | +2. Import via cdn |
| 10 | +```html |
| 11 | +<script src="https://unpkg.com/dropkit.js-test/dist/umd/index.js"></script> |
83 | 12 | ``` |
84 | 13 |
|
85 | | -This will create a symbolic link from globally-installed example-typescript-package to **node_modules/** of the current folder. |
86 | | - |
87 | | -You can then create a, for example, **testnum.ts** file with the content: |
88 | | - |
89 | | -```ts |
90 | | -import { Num } from 'example-typescript-package' |
91 | | -console.log(new Num(5).add(new Num(6)).val() === 11) |
92 | | -``` |
93 | | - |
94 | | -If 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. |
95 | | - |
96 | | -Whenever you want to uninstall the globally-installed example-typescript-package and remove the symlink in the global folder, run: |
97 | | - |
98 | | -```bash |
99 | | -npm uninstall example-typescript-package -g |
100 | | -``` |
101 | | - |
102 | | -### Prepare to publish |
103 | | - |
104 | | -Create an [npm](https://www.npmjs.com/) account. |
105 | | - |
106 | | -<details><summary><strong>Click to read this section if you do manual publishing</strong></summary> |
107 | | - |
108 | | -#### Manual publishing to npm |
109 | | - |
110 | | -Log in: |
111 | | - |
112 | | -```bash |
113 | | -npm adduser |
114 | | -``` |
115 | | - |
116 | | -And publish: |
117 | | - |
118 | | -```bash |
119 | | -npm publish |
120 | | -``` |
121 | | - |
122 | | -</details> |
123 | | - |
124 | | -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. |
125 | | - |
126 | | -#### CI publishing to npm |
127 | | - |
128 | | -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. |
129 | | - |
130 | | -If you use 2FA, then make sure it's enabled for **authorization** only instead of **authorization and publishing** (**Edit Profile** -> **Modify 2FA**). |
131 | | - |
132 | | -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. |
133 | | - |
134 | | -#### CI publishing to GitHub Packages |
135 | | - |
136 | | -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". |
137 | | - |
138 | | -Change `scope: '@tomchen'` to your own scope in **.github/workflows/publish.yml**, also change `addscope` in **package.json**. |
139 | | - |
140 | | -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/publish.yml** |
141 | | - |
142 | | -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/publish.yml**. |
143 | | - |
144 | | -(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)) |
145 | | - |
146 | | -### Publish |
147 | | - |
148 | | -Now everything is set. The example package has automated tests and upload (publishing) already set up with GitHub Actions: |
149 | | - |
150 | | -- 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. |
151 | | -- 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. |
152 | | - - [`npm version`](https://docs.npmjs.com/cli/version/) / [`yarn version`](https://yarnpkg.com/cli/version) is useful to create tags. |
153 | | - - (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`. |
154 | | - - (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** |
155 | | - - Note: `preversion`, `postversion` doesn't work in yarn v2 |
156 | | - |
157 | | -For npm registry: you can unpublish a version or the whole package but can never re-publish the same version under the same name. |
158 | | - |
159 | | -If 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. |
160 | | - |
161 | | -## Notes |
162 | | - |
163 | | -- It uses npm but you can easily switch to yarn, of course (remember to change all "npm" in `scripts` in the file **package.json**) |
164 | | - - Whether you use npm as your package manager ≠ Whether you can publish to the npm registry |
165 | | -- Works fine in VS Code. In my configuration **.eslintrc** and **.prettierrc** cooperate perfectly |
166 | | -- See `scripts` in **package.json** for other predefined script commands |
167 | | -- [pinst](https://github.com/typicode/pinst) is used to solve [a problem of husky](https://typicode.github.io/husky/#/?id=yarn-2) |
168 | | -- 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) |
169 | | - |
170 | | -## References |
171 | | - |
172 | | -- [Creating and publishing unscoped public packages - npm docs](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages) |
173 | | -- [npm-publish - npm docs](https://docs.npmjs.com/cli/v6/commands/npm-publish) |
174 | | -- [Publishing - TypeScript docs](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) |
175 | | -- [Publishing Node.js packages - GitHub Docs](https://docs.github.com/en/free-pro-team@latest/actions/guides/publishing-nodejs-packages) |
| 14 | +## Example |
| 15 | +```html |
| 16 | +<!-- Import DropKit.js library --> |
| 17 | +<script src="https://unpkg.com/dropkit.js-test/dist/umd/index.js"></script> |
176 | 18 |
|
177 | | -Btw, if you want to publish Python package, go to [Example PyPI (Python Package Index) Package & Tutorial / Instruction / Workflow for 2021](https://github.com/tomchen/example_pypi_package). |
| 19 | +<script> |
| 20 | + // On Mint button click |
| 21 | + $("#mint_btn").click(async function () { |
| 22 | + const drop = await DropKit.create('x-api-key-here'); // Supply API key |
| 23 | + await drop.mint(1); // Number of NFTs to mint |
| 24 | + }); |
| 25 | +</script> |
| 26 | +``` |
0 commit comments