How to Open source FE package 101 | Ackee frontend cookbook

Initialize

Log into the NPM

Create package.json with guide

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 , 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 scripts for any script defined in scripts section, eg. prebuild, postbuild.

You can use prepublishOnly script to run just before publishing to npm registry.

Transpilation

Babel has an option --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 imports & exportss

ESM - Transpiled ES Modules compatible sources. No ES6 features, uses imports & exportss. 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.

It’s not an easy topic and it’s getting complicated even more as Node.JS 12 supports MJS (ESM native implementation) natively now.

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

mainIt is a primary entry point for modules system. Should always point to CommonJS compatible sources.

module - Not an official field, rather a proposal understand by code bundlers like rollup or webpack. 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 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 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 in package.json.

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

Version

Evey good package must follow semantic versioning 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 but it’s not an obligation.

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

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.

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

If you want to test package installation

Publish

Release to the NPM registry is done with command

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.

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 (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.

GH actions

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

An example is in lokse repository

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

Package deprecation

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

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 and yarn workspaces.

You can take an inspiration from Resizin js respository.