Skip to content

Commit b38646e

Browse files
committed
Update README
1 parent 720432b commit b38646e

File tree

5 files changed

+24
-173
lines changed

5 files changed

+24
-173
lines changed

.github/workflows/publish.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ jobs:
4444
with:
4545
node-version: '14.x'
4646
registry-url: 'https://npm.pkg.github.com'
47-
scope: '@tomchen'
47+
scope: '@eventdrip'
4848
- run: npm run addscope
4949
- name: Publish to GitHub Packages
5050
run: npm publish

README.md

Lines changed: 19 additions & 170 deletions
Original file line numberDiff line numberDiff line change
@@ -1,177 +1,26 @@
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-
[![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&label=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)
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-
[![Use the template](https://img.shields.io/static/v1?label=&message=Click%20here%20to%20use%20this%20package%20as%20a%20template%20to%20start%20a%20new%20repo%20on%20GitHub&color=brightgreen&style=for-the-badge)](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
342

3+
## Installation
4+
1. Install via npm
355
```bash
36-
npm i
6+
$ npm install dropkit.js
377
```
388

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>
8312
```
8413

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>
17618

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+
```

config/webpack.config.js

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@ module.exports = {
66
output: {
77
path: path.resolve(__dirname, '../dist/umd'),
88
filename: 'index.js',
9-
library: 'exampleTypescriptPackage',
9+
library: 'DropKit',
1010
libraryTarget: 'umd',
11+
libraryExport: "default",
1112
globalObject: 'this',
1213
},
1314
module: {

package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "dropkit.js",
3-
"version": "1.0.0",
3+
"version": "0.0.1",
44
"description": "",
55
"main": "dist/cjs/index.js",
66
"module": "dist/esm/index.js",

src/index.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
import DropKit from './DropKit'
22

33
export default DropKit
4+

0 commit comments

Comments
 (0)