fallback-dependencies
A Node.js module that allows you to add git repo dependencies to your Node.js app from a cascading list of fallback locations. This module was built and is maintained by the Roosevelt web framework team, but it can be used independently of Roosevelt as well.
Usage
First declare fallback-dependencies
in devDependencies
in your app.
Then add a fallbackDependencies
entry to your package.json
alongside your dependencies
, devDependencies
, etc.
Here's an example:
"fallbackDependencies": {
"dir": "lib",
"repos": {
"some-private-dependency": [
"https://some.private.git.repo.somewhere",
"https://some.private.git.repo.somewhere.else",
],
"some-other-private-dependency": [
"https://some.other.private.git.repo.somewhere",
"https://some.other.private.git.repo.somewhere.else",
]
},
"reposFile": "fallback-dependencies.json"
}
Lastly, add a postinstall
script to your npm scripts to execute the fallback-dependencies
script after you install other dependencies:
"scripts": {
"postinstall": "node node_modules/fallback-dependencies/fallback-dependencies.js"
},
You can also write your postinstall
script to fail silently if the fallback-dependencies.js file is not found for whatever reason, e.g.:
"scripts": {
"postinstall": "node -e \"try { require('node_modules/fallback-dependencies/fallback-dependencies.js') } catch (e) {}\""
},
By default, fallback-dependencies
will not install the devDependencies
of a given repo that is cloned. If you want to do so for any repo, put it in a fallbackDevDependencies
block instead of a fallbackDependencies
block in your package.json
.
To clone a specific git tag, add -b tag_name
to the URL, e.g. "https://some.private.git.repo.somewhere -b 1.0.5"
.
To skip installing dependencies for a specific fallback-dependency, add -skip-deps
to the end of the URL string, e.g. "https://some.private.git.repo.somewhere -b 1.0.5 -skip-deps"
To prevent a fallback-dependency from being installed in a situation where the repo is not a direct dependency of the root project, append the :directOnly
flag to the end of the dependency name, e.g. "some-private-dependency:directOnly": [ ... ]
.
To move a preferred domain up to the top of list of fallback dependencies to try regardless of the order specified in the app's config, set the environment variable FALLBACK_DEPENDENCIES_PREFERRED_WILDCARD
to a string to match in the URL list.
API
-
dir
[String]: What directory to deposit fallback dependencies into.- Default:
fallback_dependencies
.
- Default:
-
repos
[Object] of [Arrays] of [Strings]: A list of dependencies similar to thedependencies
field in package.json, but instead of supplying a string for where to fetch it, you supply an array of strings of possible locations to fetch it from. This script will attempt to fetch it from the first location, then if that fails will fallback to the second possible place to get it from, and so on until it runs out of places to try.- Default:
{}
.
- Default:
-
reposFile
[String]: Relative path to a JSON file that contains a list of repos formatted the same as therepos
entry. If bothrepos
andreposFile
are supplied, the two lists will be merged.- Default:
{}
. - Example:
// fallback-dependencies.json { "some-private-dependency": [ "https://some.private.git.repo.somewhere", "https://some.private.git.repo.somewhere.else", ], "some-other-private-dependency": [ "https://some.other.private.git.repo.somewhere", "https://some.other.private.git.repo.somewhere.else", ] }
- Default:
All params are optional, but the module won't do anything unless you supply at least repos
or reposFile
.