# How to Open source FE package 101

## Initialize

Log into the NPM

$ npm login 
# or
$ npm adduser

Create package.json with guide

$ npm init 
# or
$ yarn init

> Tip: Use `-y` arg to answer yes to all questions in guide

We distinguish between unscoped and scoped packages and also between private and public packages.

If you wish to add some cool fancy badges, look at [shields.io](https://shields.io) , pick some and add them into you README.md.

#### Unscoped packages

Unscoped packages are always public. Has the name not starting with `@` like `react`, `lodash`, etc.

#### Scoped packages

Packages scoped to user or organization which has to be created in NPM.

Scoped packages can be public or private but for private packages you must have paid organization account at NPM.

Scoped packages are **private by default** so for public open source packages you need to pass `--access public` when publishing to the registry.

## Prepare

We can use [`pre` and `post`](https://docs.npmjs.com/cli/v7/using-npm/scripts#pre--post-scripts) scripts for any script defined in `scripts` section, eg. `prebuild`, `postbuild`.

You can use [`prepublishOnly`](https://docs.npmjs.com/cli/v7/using-npm/scripts#life-cycle-scripts) script to run just before publishing to npm registry.

### Transpilation

Babel has an option [`--copy-files`](https://babeljs.io/docs/en/babel-cli#copy-files) that can be used to copy files that are not about to transpile.

#### Targets
For Frontend packages you'll usually target two kinds of sources: CJS and ESM (some packages also support UMD)

* **CJS** - Transpiled CommonJS compatible sources. No ES6 features, no `import`s & `exports`s
* **ESM** - Transpiled ES Modules compatible sources. No ES6 features, uses `import`s & `exports`s. This kind of sources is usually leveraged by bundlers to tree shake unused sources.
* **UMD** - Stands for Universal Module Definition. Transpiled sources that supports various module systems, see [examples](https://github.com/umdjs/umd/tree/master/templates).

It's not an [easy topic](https://dev.to/remshams/rolling-up-a-multi-module-system-esm-cjs-compatible-npm-library-with-typescript-and-babel-3gjg) and it's [getting complicated even more](https://2ality.com/2019/10/hybrid-npm-packages.html) as Node.JS 12 supports MJS (ESM native implementation) natively now.

There is several package.json fields used to refer different sources types:

* [**`main`**](https://docs.npmjs.com/cli/v7/configuring-npm/package-json#main)- It is a primary entry point for modules system. Should always point to CommonJS compatible sources.
* [**`module`**](https://medium.com/webpack/webpack-and-rollup-the-same-but-different-a41ad427058c) - Not an official field, rather a [proposal](https://github.com/nodejs/node-eps/blob/4217dca299d89c8c18ac44c878b5fe9581974ef3/002-es6-modules.md#51-determining-if-source-is-an-es-module) understand by code bundlers like [rollup](https://github.com/rollup/rollup/wiki/pkg.module) or [`webpack`](https://www.jonathancreamer.com/how-webpack-decides-what-entry-to-load-from-a-package-json/). Should point to an ES modules sources.
* **`browser`** - Point to package bundle for its usage in browser.

Webpack looks first for the `module`, and lastly `main`.

### Files

You should control what will be published inside package and **never publish any sensitive information** like private keys, passwords, etc.

> If it happens you accidently publish what you didn't intend, there is still way [how to unpublish](https://docs.npmjs.com/unpublishing-packages-from-the-registry#how-to-unpublish) but sooner you realize and make it, the easier it will be.

#### Blacklisting

When publishing NPM uses file `.npmignore` to determine which files won't be included into the package. File `.npmignore` uses same syntax as `.gitignore`.

If there is no `.npmignore` in a repo, `.gitignore` is used to determine omitted files and folders.

Remember that `.npmignore` has precedence over `.gitignore` and only one of them is used. If there is something in `.gitignore` you want to make part of package, create `.npmignore` and fill it according to your needs.

There is a list of [files are ignored by default](https://docs.npmjs.com/cli/v7/using-npm/developers#keeping-files-out-of-your-package) and should never get published like `node_modules`, `.DS_Store`, `.git`, `.npmrc`, `npm-debug.log`, etc.

On the other hand, these files are never ignored so you don't need to list them in the ignore file: `package.json`, `README`, `CHANGELOG`, `LICENSE`, them `main` field file.

#### Whitelisting

You can also choose inverse approach and select files to include in the package, using [`files` field](https://docs.npmjs.com/cli/v7/configuring-npm/package-json#files) in `package.json`.

> Files included with the `files` field cannot be excluded through .npmignore or .gitignore.

### Version

Evey good package **must follow** [semantic versioning](https://semver.org) principles when creating new package version.

New package release requires `version` field in `package.json` to be changed. We can use `version` command for that

> Note: NPM recommends [first package version to be `1.0.0`](https://docs.npmjs.com/about-semantic-versioning) but it's not an obligation.

#### [`npm version`](https://docs.npmjs.com/cli/v7/commands/npm-version)

`npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease [--preid=<prerelease-id>] | from-git]`

* Bumps version in `package.json` (also in `package-lock.json` or `npm-shrinkwrap.json` if present).
* create a version commit
* create a version tag

#### [`yarn version`](https://classic.yarnpkg.com/en/docs/cli/publish)

`yarn version` starts a guide for setting new version, alternatively you can use syntax similar to `npm version`

`yarn version [--new-version <version> | --major | --minor | --patch | --premajor | --preminor | --prepatch | --prerelease [--preid <pre-identifier>] ]`

Makes the same 3 steps as the `npm version`.

You can hook into the version lifecycle with these `package.json#scripts`: `preversion`, `version`, `postversion`.

We utilize the `version` script for [updating changelog](https://github.com/AckeeCZ/jerome/blob/master/package.json#L24).

> Tip: Use `.yarnrc` to change version commit message with `version-git-message "🔖 Version %s"` or tag prefix with `tag-version-prefix ""`.

https://stackoverflow.com/questions/29738381/how-to-publish-a-module-written-in-es6-to-npm

## Release

### Test package

If you're not sure what will be published into the registry, test packing it

$ npm pack
$ open package_name.tgz

If you want to test package installation

$ npm install ./path_to_package_dir
# or
$ yarn add ./path_to_package_dir

### Publish

Release to the NPM registry is done with command

$ npm publish

which pack and release into standard public NPM registry `https://registry.npmjs.org/`

> Note: Be aware that `yarn publish` also prompts for new version.

When publishing new version you can specify [release tag](). By default **`latest` tag is used** with standard publish. But we can also use `alpha` or `beta` tags to mark version as a prerelease and make sure it won't be accidentally installed. You can see package latest, beta, and alpha versions in [list of versions](https://www.npmjs.com/package/@ackee/antonio).

$ npm publish --tag beta

### Manual publish

Just run the publish command from the command line.

### Automated publish

By CI (Github, Gitlab) usually triggered on push of new version tag.

You need to have an [NPM access token](https://docs.npmjs.com/creating-and-viewing-access-tokens) (of type Automation) to do this.

#### Travis

Defined by `travis.yml` file in repository root. There is already a guide about [How to setup Travis pipeline](https://frontend-cookbook.ack.ee/#/pages/GithubPipeline).

#### GH actions

Defined by yaml workflow definition in `.github/workflows` directory.

An example is in [`lokse` repository](https://github.com/AckeeCZ/lokse/tree/master/.github/workflows)

On Github you can use Travis CI or GH Actions. We've been using Travis CI for a long time but now time has come to start using GH Actions.

Reasons to use GH Actions over Travis CI:

* They're integrated into the Github UI whereas Travis is a standalone service on different url with differen UI
* There are more flexible, workflows consists of actions and there is an actions marketplace
* Easier to set up, we can use one `NPM_TOKEN` across our repositories
* Executing GH actions is faster

### Create GH release

It's a good practise to fill in also [Github Release](https://docs.github.com/en/github/administering-a-repository/about-releases) with release notes once you publish a new version since developers also looks for what changed right there.

## Other

### More entry points

If you need you can utilize pattern with more than one package.json in the repo as [used in `@ackee/jerome`](https://github.com/AckeeCZ/jerome/blob/master/antd/package.json)

my-npm-pkg/
   package.json # pkg.main points to index
   src/
     index.js
     alternative-index.js
   alternative/
     package.json   # pkg.main points to alternative-index

### Package deprecation

In case you decide package to be obsolete and not usable, use command

$ npm deprecate

to mark it deprecated.

### Monorepos

In our terms monorepo means one repository holding several packages that are published separately.

How to works with monorepos is for standalone topic as setuping it is a bit complicated. You're gonna find useful tools like [Lerna](https://github.com/lerna/lerna) and yarn [workspaces](https://yarnpkg.com/lang/en/docs/workspaces/).

You can take an inspiration from [Resizin js respository](https://github.com/AckeeCZ/resizin-js/).