godaddy / u2d

U2D

u2d › up to date

tty	non-tty

A developer experience tool to enforce environment and dependency version policies.

• Want all of your projects to use the same node and npm semver range?
• Same react major version?
• How about detecting duplicate packages in a project's node_modules?
• Or even making sure certain dependencies are never installed?

Use u2d anywhere in your projects lifecycle to get instant feedback to protect releasing code integrating with unsupported versions. Have several projects and want a single configuration? Host your configuration remotely on your own CDN, or use something like https://jsonbin.io/.

TOC

• Install
• CLI
  • Options
• Node
  • Options
• Checks
  • Engines
  • Packages
• Config
• Environment
• Manager
• Level

Install

$ npm i -D u2d

CLI

The u2d CLI was built to be quick and simple, allowing developers to run it anywhere at any step in the development process.

In a terminal

$ npx u2d 

Or as an npm script

{
  "scripts": {
    "prepare": "u2d"
  }
}

CLI Options

flag	description	type	default
-p | --cwd	working directory	string	process.cwd()
-c | --config	configuration file or url	string	auto detected
-m | --manager	package manager	npm | pnpm | yarn	auto detected
-d | --depth	package node_modules depth	Infinity | number	Infinity
-e | --env	package node_modules environment	local | dev | prod | global	local
-l | --log	logging level	error | warn | info | debug	info
-a | --local	enable package.json engines/dependencies
-b | --bail	disable error collection
-s | --silent	disable logging
-o | --show-config	print config and exit
-h, --help	display help

You can also run npx u2d --help locally

Node

You can directly import u2d in your node projects too. Useful for injecting into scripts or actions, allowing you to manually handle results.

// Supports ESM
import u2d from 'u2d';
// and CJS
const u2d = require('u2d').default;

u2d({ /* options */ }).then(({ skips, infos, errors, warnings }) => {
  if (errors.length) {
    process.exit(1);
  }
});

Node Options

name	description	type	default
cwd	working directory	string	process.cwd()
config	configuration file or url	string | object	auto detected
manager	package manager	npm | pnpm | yarn	auto detected
depth	package node_modules depth	Infinity | number	Infinity
env	package node_modules environment	local | dev | prod | global	local
log	logging level	error | warn | info | debug	info
local	enable package.json engines/dependencies	boolean	false
bail	disable error collection	boolean	false

Checks

A check is a semver range to run against an found version. A check must define a pass range, and optionally a fail range and/or a help description.

Example node check, will pass on 16+, warn on 10-15, and fail on <10.

{
  "engines": {
    "node": {
      "pass": ">=16",
      "fail": "<10",
      "help": "https://letmegooglethat.com/?q=update+node"
    }
  }
}

Checks can also be expressed using shorthand

input	output	description
true	{ pass: '*' }	always pass, use to override config
false	{ pass: '<*' }	always fail, use to error if installed
string	{ pass: string }	provide pass
number	{ pass: '^number' }	provide pass, with caret
[pass, fail]	{ pass, fail }	provide pass and fail
[pass, true]	{ pass, fail: '*' }	provide pass, use to require
[pass, fail, help]	{ pass, fail, help }	provide pass, fail and help

Engine Checks

These checks are explicit, as it will check the environment of the cwd.

• node
• npm
• pnpm
• yarn

Package Checks

Currently only supporting npm, u2d will check the installed packages based on the env and specified depth.

Config

By default, u2d doesn't do much without some configuration. You can use your local package.json as a starting point, by enabling the local option. Simply add one of the files below, or define your own and provide using a config option.

• u2d property in package.json
• .u2drc JSON file
• .u2d with .json | .js | .cjs extension
• u2d.config with .js | .cjs extension

This configuration can live locally, or externally; we suggest both! Hosting externally enables multiple projects to use a single source of configuration. Here's an example hosted at https://jsonbin.io/. Hosting locally allows individual projects to add project specific configuration and/or override external policies.

The result can expose any node option, with the addition of the following

name	description	type
extends	configuration file	string
engines	environment checks	{ [key: string]: Check }
packages	dependency checks	{ [key: string]: Check }

Example

module.exports = {
  extends: 'https://api.jsonbin.io/v3/b/628e7498402a5b38020d5cb1', // A basic example
  local: true, // Use `package.json` engines/dependencies
  engines: {
    node: 16, // Warn if not on node@^16
    npm: '7 - 8' // Warn if not npm@>=7 <9
  },
  packages: {
    'left-pad': false, // Error if installed
    'lodash': [4, true], // Error if not on lodash@^4
    'react': true // Allow any version
  }
}

Environment

The env config refers to the type of dependencies to run package checks against. By default, u2d uses local to check your cwd for matching node_modules packages.

export const Environment = {
  GLOBAL: 'global',
  LOCAL: 'local',
  PROD: 'prod',
  DEV: 'dev'
} as const;

env	description
global	Check all node_modules packages in the global install prefix
local	Check all node_modules packages in the cwd
prod	Check only non-development node_modules packages in the cwd
dev	Check only development node_modules packages in the cwd

Manager

Currently, u2d only supports npm but recognizes the value in handling multiple project management solutions. This limitation only applies to package checks.

export const Manager = {
  NPM: 'npm',
  PNPM: 'pnpm',
  YARN: 'yarn'
} as const;

manager	description
npm	https://www.npmjs.com/
pnpm	https://pnpm.io/
yarn	https://yarnpkg.com/

Level

By default u2d uses the info log level to communicate what was processed to give developers critical information about the executed checks. The level also applies to capturing results when using the node export.

export enum Level {
  error = 0,
  warn = 1,
  info = 2,
  debug = 3
}

level	description
error	Capture only exceptions and/or failed checks
warn	Capture non-pass checks, and errors
info	Capture pass checks, warnings and errors
debug	Capture everything, including skips

License

u2d is MIT licensed

u2d's Issues

Feature: Detect non-deduped dependencies

A flag to check duplicates in all node_modules

Feature: Add glob support

Allow checks to use glob syntax

{
  "packages": {
    "{react,react-dom}": 18,
    "@radpack/*": 1
  }
}

Feature: Add `yarn` and `pnpm` support

https://github.com/godaddy/u2d/blob/v1.0.0/src/tasks/pkg.ts#L20-L23

Feature: Fix package.json versions

For whatever reason, a package.json semver can be behind what is currently installed according to the package-lock.json. Feature would be to add a command to update the versions to match what is currently installed, so developers can easily confirm what version is being referenced without having to cross-check the lock file. Something like u2d --sync-local