GregorSondermeier / research-patch-package

Researching and assessing if patch-package is a reasonable tool to use

Research patch-package

Researching and evaluating if patch-package is a feasible tool to use.

This project was initialized with Typescript Webpack Boilerplate.

The results

Pros	Cons
Enables quick modification or configuration change of an npm library which might not offer an API or something similar itself.	Deep knowledge of the respective library is required
	Patch files are difficult to read
	Working within the node_modules folder is cumbersome
	Complex libraries => complex patches
	When updating a patched library there is no warranty that the patches continue to work as intended. The target files could have a changed structure so that the patches cannot be applied automatically.
	Transitive dependencies increase complexity yet again
	Repo has many open issues and unmerged PRs
	Anti Pattern

Also, from patch-package's readme:

Isn't this dangerous?

Nope. The technique is quite robust. Here are some things to keep in mind though:

• It's easy to forget to run yarn or npm when switching between branches that do and don't have patch files.
• Long lived patches can be costly to maintain if they affect an area of code that is updated regularly and you want to update the package regularly too.
• Big semantic changes can be hard to review. Keep them small and obvious or add plenty of comments.
• Changes can also impact the behaviour of other untouched packages. It's normally obvious when this will happen, and often desired, but be careful nonetheless.

So should you use it?

For smaller DIY-type projects when you want to try things and do no harm, sure go ahead.

If you're working on a complex project which involves many contributors, has many and complex dependencies and which is used in production, I'd say no.
The drawbacks clearly outweigh the benefits.
For every dependency upgrade you do (be it major, minor or patch), chances are your patches are not working anymore. Cumbersume manual labour would be required to make the patches work again.

If you need a library to change its implementation, it's better to create an issue (maybe already a PR) on that library's GitHub page and contribute to a sustainable solution instead of a dirty quick fix.

If your requirements differ too much from what the library offers, it's better to look for a different library or create one yourself.

---

Typescript Webpack Boilerplate

A starter frontend boilerplate built with:

• TypeScript
• Babel (7)
• Webpack (5)
• PostCSS
• Jest
• ESLint
• Stylelint

This also uses lint-staged for running pre-commit checks.

Features

• Support for both TypeScript and JavaScript as needed.
• May be extended to be used with React, Vue.js, or Angular.
• Minification of TypeScript/JavaScript and CSS processed files.
• Assets optimization.
• Webpack Dev Server plugin for local development.
• Webpack Bundle Analyzer for visualising script output and usage.

Prerequisites

• NodeJS
• npm

Folder structure

src
└── css
│    ├── all
│    └── styles.css
├── index.ts
public
├── assets
├── favicon.ico
└── index.html

• src
  • The entry typescript file is index.ts.
  • The helpers/set-message folder is a sample folder for how to test using Jest.
  • Local files are imported using the '@' alias. See index.ts file for example.
• scr/css
  • Add your styles here and @import them to the entry styles.css file.
• public
  • Edit the index.html in the public folder to suite your needs.
  • Replace the favicon.ico with your own icon.
• public/assets.
  • Add your assets, to the assets folder.

Configuration

You may change the configuration for Webpack within the webpack folder.

Setup

Install dependencies

Run:

  npm i

Development

Server

Run:

  npm run serve

This will create a server at http://localhost:9000/ or at the port number specified in the webpack/configuration/config.js file.

Automatically reloads after each file change.

Production build

Run:

  npm run build

Will output all build files into the dist folder.

Testing (Jest)

Run:

  npm run test

or watch files

  npm run test:watch

Linting

All files

Run:

  npm run lint:all

To fix all possible errors automatically run:

  npm run lint:all:fix

TypeScript (tsc)

Run:

  npm run lint:check-types

There is no automatic fix option for TypeScript.

TypeScript and JavaScript (ESLint)

Run:

  npm run lint:scripts

To fix all possible errors automatically run:

  npm run lint:scripts:fix

Styles (StyleLint)

Run:

  npm run lint:styles

To fix all possible errors automatically run:

  npm run lint:styles:fix

Check bundle size

Run:

  npm run check-size

This will create a server at http://localhost:8888/ or at the port number specified using the -p or --port option via the cli.

License

MIT