{"_id":"@domir/relative-deps","name":"@domir/relative-deps","dist-tags":{"latest":"1.0.5"},"versions":{"1.0.5":{"name":"@domir/relative-deps","version":"1.0.5","description":"Installs local dependencies for optimal developer experience","main":"index.js","private":false,"scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"bin":{"relative-deps":"cli.js"},"repository":{"type":"git","url":"git+https://github.com/mweststrate/relative-deps.git"},"keywords":["yarn","npm","link","relative","dependencies"],"author":{"name":"Michel Weststrate"},"license":"MIT","bugs":{"url":"https://github.com/mweststrate/relative-deps/issues"},"homepage":"https://github.com/mweststrate/relative-deps#readme","dependencies":{"checksum":"^0.1.1","globby":"^9.2.0","lilconfig":"^2.0.6","lodash":"^4.17.15","read-pkg-up":"^6.0.0","rimraf":"^2.6.3","tar":"^6.0.5","yargs":"^15.0.2","yarn-or-npm":"^3.0.1"},"gitHead":"174961772ece7c61b42c29a7e4edd221c238e91b","_id":"@domir/relative-deps@1.0.5","_nodeVersion":"16.14.2","_npmVersion":"8.5.0","dist":{"integrity":"sha512-kgG+AvIdaTcrhWjiDnmtae+E5chPUGHCVZOwFuOFvMI0jdPOuUt9o/jm4k4PEFZOOQymlRfFW9o5+nKJSa2/hQ==","shasum":"17e69c30677c55f2d0d727e8362f3ba60964f790","tarball":"https://registry.npmjs.org/@domir/relative-deps/-/relative-deps-1.0.5.tgz","fileCount":5,"unpackedSize":20059,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIHR176kpnksBYArK/ei2dn7+vYORnVbi7pQhZZZc5DThAiEA5aDi7JtRJ5ysO3+G0A86Vx1v8NuWDnuKKQQwNgP0m2c="}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJjH0xNACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2VmrPjQ//fvL7BAwhMPNx5vYa8tsp1yUdohCGHgavhfvfgkq1VxOFIjUc\r\nlzDWkO2+SiGIo5ElyapZOJkJMz4jox8OsgcBqzvCMDEzy6N7GFZ1ySR6ongw\r\nNQWFyao0oXVb5lk2iAtF/cax3tRgdMZn6XVmdME3MyzbKOg3m+K5L/k5Z/cH\r\nrJy5KqCNg/EvcFHg3JVqFnM8lHNIpLKOvcRKH/p/Psut2gr3HWeaGlasVkTt\r\npF2TG5ThStKkK10wJaCGBW17yrOidOlnASFzKChm0qabzZxzhUqL68bU6oOI\r\n1WCW9N8IM0BpVWy80x6s1sdqdu4PAYpNLH5XuhmAaJS8l7sAd+w1zqGVeOuk\r\nTlrYPpc9kLtWlNntvnjVadqOF9zSqtwRGetQCis5RSs5Kibi5u69rYceaTWi\r\nORrgziNkVX1n49veW1ZNf0/yt3McW4vNindLXvscp2P4xtSRfvTgZFeYhuzQ\r\nBVeCjkRm/2dZoPCApKw+MImBtSrCPSTOL+BF8DXZ0e7YSCsvJ03STV1FvXBj\r\nFn3lIlyrWs6kzpaOqat8gPviXbvX6JuxuVmF83kL9eItrZaewxpCUEMC6W2T\r\nZr7B/Mwj1FdIPK9n2klv+pmP67OrjDH6y7s8B634Aw7dzKj1w+iZskdBmqcg\r\n+aFcTircf2VQ0eXeN4NJ+uwgTE+Khi/Q/58=\r\n=NRzq\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"domir","email":"domi.github@gmail.com"},"directories":{},"maintainers":[{"name":"domir","email":"domi.github@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/relative-deps_1.0.5_1662995533776_0.8526697133717891"},"_hasShrinkwrap":false}},"time":{"created":"2022-09-12T15:12:13.659Z","1.0.5":"2022-09-12T15:12:13.920Z","modified":"2022-09-12T15:12:14.108Z"},"maintainers":[{"name":"domir","email":"domi.github@gmail.com"}],"description":"Installs local dependencies for optimal developer experience","homepage":"https://github.com/mweststrate/relative-deps#readme","keywords":["yarn","npm","link","relative","dependencies"],"repository":{"type":"git","url":"git+https://github.com/mweststrate/relative-deps.git"},"author":{"name":"Michel Weststrate"},"bugs":{"url":"https://github.com/mweststrate/relative-deps/issues"},"license":"MIT","readme":"# relative-deps\n\n[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.me/michelweststrate)\n<a href=\"https://www.buymeacoffee.com/mweststrate\" target=\"_blank\"><img src=\"https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png\" alt=\"Buy Me A Coffee\" style=\"height: 22px !important;width: auto !important;\" ></a>\n\n_Installs dependencies from a local checkout, and keeps them in sync, without the limitations of `link`_\n\n---\n\n# Summary\n\nRelative deps introduces an additional dependency section in `package.json`, called `relativeDependencies`.\nThis section contains paths to the local sources of any dependency, that will be built and installed over the publicly available versions, when needed.\n\nExample `package.json`:\n\n```json\n{\n  \"name\": \"my-project\",\n  \"dependencies\": {\n    \"my-cool-library\": \"0.1.0\"\n  },\n  \"relativeDependencies\": {\n    \"my-cool-library\": \"../../packages/my-cool-library\"\n  },\n  \"scripts\": {\n    \"prepare\": \"relative-deps\"\n  },\n  \"devDependencies\": {\n    \"relative-deps\": \"^1.0.0\"\n  }\n}\n```\n\nWhen the relative path can be found, the library at this path will be re-built and re-installed into this project, if the source files have been changed during `prepare`.\n\nThe normal `my-cool-library` dependency will be defaulted to, for those that don't have a local checkout of `my-cool-library`, and to resolve transitive dependencies.\n\nAn example setup, where examples project are linked to their hosting library, can be found [here](https://github.com/mobxjs/mst-gql/pull/40/commits/4d2c0858f8c44a562c0244466b56f79b0ed7591b).\n\n# Why\n\n### The problem\n\nWorking on libraries that have examples embedded in the same git repository is usually tricky, as the examples are usually built against the public, published version of the library; the version that is mentioned in their `package.json`.\n\nWhen working maintaining a project though, it is much more useful to work against the locally checked out version of the library. Published or not.\n\n### The problems with existing solutions\n\nThere are a few existing solutions, but they have their own limitations:\n\n- `yarn link` / `npm link`. These work only if there are no peer / shared dependencies involved. If there are shared dependencies, the linked library will resolve those in their _own_ `node_modules`, instead of the `node_modules` of the hosting project, where it would normally be looked up. This results in peer dependencies ending up \"twice\" in the dependency tree, which often causes confusing behavior.\n- `yarn workspaces`. Those solve the above issue by putting all dependencies in one large root level `node_modules`. However, this setup is in practice quite obtrusive to the whole development setup.\n\n### How is relative deps different?\n\nRelative deps doesn't fight the problem but tries to emulate a \"normal\" install. It builds the \"linked\" library on `prepare` (that is, after installing all deps), packs it, and unpacks it in the `node_modules` of the hosting project. Since there is no linking, or shared `node_modules` involved, the folder structure ends up to be exactly the same as if the thing was installed directly from `yarn` / `npm`. Which avoids a plethora of problems.\n\nSince building a linked package every time `yarn install` is run is expensive, this tool will take a hash of the directory contents of the library first, and only build and install if something changed.\n\n# Usage\n\n## Installation\n\n```bash\nnpx relative-deps init\n```\n\nOptions:\n\n- `--script`\n\nAlias `-S`. Default: `prepare`. Script name which is using for running `relative-deps`.\n\nRunning this script will install `relative-deps`, add script and initialize empty `relativeDependencies` section.\n\n```json\n{\n  \"name\": \"my-project\",\n  \"devDependencies\": {\n    \"relative-deps\": \"^1.0.0\"\n  },\n  \"relativeDependencies\": {},\n  \"scripts\": {\n    \"prepare\": \"relative-deps\"\n  }\n}\n```\n\nOptionally, you can add this step also for more scripts, for example before starting or building your project, for example:\n\n```json\n{\n  \"name\": \"my-project\",\n  \"scripts\": {\n    \"prepare\": \"relative-deps\",\n    \"prestart\": \"relative-deps\",\n    \"prebuild\": \"relative-deps\",\n    \"pretest\": \"relative-deps\"\n  }\n}\n```\n\nIn general, this doesn't add to much overhead, since usually relative-deps is able to determine rather quickly (~0.5 sec) that there are no changes.\n\n## Adding a relative dependency\n\nRunning following script will initialize `relative-deps` if not initialized yet, find the package at the provided path, install it as normal dependency and pack relative-dependency.\n\n```bash\nnpx relative-deps add ../../packages/my-cool-library\n```\n\nOptions:\n\n- `--dev`\n\nAlias `-D`. Installs relative dependency in `devDependencies` section.\n\n```json\n{\n  \"name\": \"my-project\",\n  \"dependencies\": {\n    \"my-cool-library\": \"0.1.0\"\n  },\n  \"relativeDependencies\": {\n    \"my-cool-library\": \"../../packages/my-cool-library\"\n  },\n  \"scripts\": {\n    \"prepare\": \"relative-deps\"\n  },\n  \"devDependencies\": {\n    \"relative-deps\": \"^1.0.0\"\n  }\n}\n```\n\nExample of a [repository migration to relative-deps](https://github.com/mobxjs/mst-gql/pull/40/commits/4d2c0858f8c44a562c0244466b56f79b0ed7591b)\n\n## Run `npx relative-deps` when devving!\n\nThe relative deps will automatically be checked for changes, based on the hooks you've set up during [installation](#installation).\n\nHowever, you can always trigger a manual check-and-build-if-needed by running `npx relative-deps` (or just `yarn`). If you are working on a project that supports\nhot reloading, this will makes sure the changes in the relative dependency will automatically show up in your project!\n\n## Watch mode\n\nYou can run `relative-deps watch` and it'll run `relative-deps` command when one of the relative dependecies changed, debounced with 500ms.\nThis can go along with config of your project to watch over the relevant packages and it will automate the process completely,\nallowing you to change a library code and to enjoy the befefit of hot-reload.\n\n# How\n\nRoughly, it works like this (obviously this can get out of date quickly):\n\n```\n- pre: yarn.lock exists or die\n- read relativeDeps from nearest package.json\n- doesn't exist? warn & exit\n- for each relativeDep:\n- check if target path exists\n  - if not, do we have the module from normal install?\n  - yes: warn\n  - no: error\n- if target path exists, does it have node modules?\n  - no: run yarn / npm install (guess which one)\n- find last modified timestamp of all files in target dir\n  (excluding node_modules, .git, excluding the directory that contains the calling project if applicable, only use git versioned files)\n- take hash and store / compare with stored\n- if changed:\n  - run yarn / npm build\n  - run pack\n  - extract package (mind scoped package names!)\n  - run yarn install --no-dev-deps in target dir\n- done\n```\n\n# Tips\n\nTip: use the `postinstall` hook wherever applicable, if your dependency manager does not support `prepare` hooks yet.\n","readmeFilename":"README.md"}