https://github.com/jasonsturges/javascript-npm-package
JavaScript library npm package template
https://github.com/jasonsturges/javascript-npm-package
boilerplate library npm package rollup template
Last synced: about 2 months ago
JSON representation
JavaScript library npm package template
- Host: GitHub
- URL: https://github.com/jasonsturges/javascript-npm-package
- Owner: jasonsturges
- Created: 2022-02-14T04:43:29.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2022-12-10T21:01:04.000Z (over 3 years ago)
- Last Synced: 2025-04-10T12:17:14.701Z (about 1 year ago)
- Topics: boilerplate, library, npm, package, rollup, template
- Language: JavaScript
- Homepage:
- Size: 109 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# JavaScript NPM Package
Scaffold JavaScript npm packages using this template to bootstrap your next library.
This boilerplate supports generating TypeScript declarations (`d.ts`) for compatibility with TypeScript projects by using JSDoc comments for types.
Project includes:
- [TypeScript](https://www.typescriptlang.org/)
- [Rollup](https://rollupjs.org/)
- [Microsoft API Extractor](https://api-extractor.com/)
- [TypeDoc](https://typedoc.org/)
Versions of this template:
- [Vite TypeScript library npm package](https://github.com/jasonsturges/vite-typescript-npm-package)
- [Vite JavaScript library npm package](https://github.com/jasonsturges/vite-npm-package)
- [Rollup JavaScript library npm package](https://github.com/jasonsturges/npm-package-boilerplate)
- [Rollup TypeScript library npm package](https://github.com/jasonsturges/typescript-npm-package)
## Getting Started
Begin via any of the following:
- Press the "*Use this template*" button
- Use [degit](https://github.com/Rich-Harris/degit) to execute:
```
degit github:jasonsturges/npm-package-boilerplate
```
- Use [GitHub CLI](https://cli.github.com/) to execute:
```
gh repo create --template="https://github.com/jasonsturges/npm-package-boilerplate"
```
- Simply `git clone`, delete the existing .git folder, and then:
```
git init
git add -A
git commit -m "Initial commit"
````
Remember to use `npm search ` to avoid naming conflicts in the NPM Registery for your new package name.
## Usage
The following tasks are available for `npm run`:
- `dev`: Run Rollup in watch mode to detect changes to files during development
- `build`: Run Rollup to build a production release distributable
- `build:types`: Run Microsoft API Extractor to rollup a types declaration (`d.ts`) file
- `docs:jsdoc`: JSDoc generated documentation in the "*docs/*" folder
- `docs:typedoc`: TypeDoc for TSDoc generated documentation in the "*docs/*" folder
- `clean`: Remove all build artifacts
## Development
While test driven development (TDD) would be a good approach to develop your library, also consider creating an app for prototyping and local testing of your library.
To test within the library, consider using [Storybook](https://storybook.js.org/). This approach runs a `storybook` script to load local source files for development.
Otherwise, follow these steps to test the package from another project:
**From your library project**, issue the `npm link` (or `yarn link`) command:
```
npm link
```
Start Rollup in watch mode:
```
npm run dev
```
**Create a test app project**, by doing the following:
To use your npm package library locally for development, create a new project in a separate folder:
```
mkdir test-app && cd test-app
npm init
```
Take the defaults from `npm init`
In the package.json of your test app, add the following two things:
- Set the `type` of your package to `module`
- Add a `start` script to execute your app
```json
"type": "module",
"scripts": {
"start": "node index.js",
},
```
Link to your library using the `npm link ` (or `yarn link `) command - be sure the `` matches your library's package.json name. For example:
```
npm link npm-package-boilerplate
```
Now, run your app via `npm start`.
As an example, if your library's "*index.ts*" file contained:
```ts
export const sayHi = () => {
console.log("Hi");
};
```
...your test app would implement an import using your package name, such as:
```ts
import { sayHi } from "npm-package-boilerplate";
sayHi();
```
## Development Cleanup
Once development completes, `unlink` both your library and test app projects.
**From your test app project**, unlink the library using `npm unlink ` (or `yarn unlink `) command:
```
npm unlink npm-package-boilerplate
```
**From your library project**, issue the `npm unlink` (or `yarn unlink`) command:
```
npm unlink
```
## Release Publishing
Update your `package.json` to next version number, and remember to tag a release.
Once ready to submit your package to the NPM Registry, execute the following tasks via `npm` (or `yarn`):
- `npm run clean` — Assure a clean build
- `npm run build` — Build the JavaScript package
- `npm run build:types` — Build API Extractor (d.ts declarations) for TypeScript compatibility
Assure the proper npm login:
```
npm login
```
Submit your package to the registry:
```
npm publish --access public
```