{"id":15660175,"url":"https://github.com/transitive-bullshit/node-compat-require","last_synced_at":"2025-05-05T20:10:18.083Z","repository":{"id":65411363,"uuid":"132246078","full_name":"transitive-bullshit/node-compat-require","owner":"transitive-bullshit","description":"Easily allow your Node program to run in a target node version range to maximize compatibility.","archived":false,"fork":false,"pushed_at":"2020-07-11T23:10:49.000Z","size":85,"stargazers_count":20,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-10T07:57:30.164Z","etag":null,"topics":["backwards-compatible","cli","compatibility","node","nodejs","npx","version"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/transitive-bullshit.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-05T12:30:47.000Z","updated_at":"2023-10-12T05:45:14.000Z","dependencies_parsed_at":"2023-01-23T00:16:00.902Z","dependency_job_id":null,"html_url":"https://github.com/transitive-bullshit/node-compat-require","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transitive-bullshit%2Fnode-compat-require","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transitive-bullshit%2Fnode-compat-require/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transitive-bullshit%2Fnode-compat-require/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transitive-bullshit%2Fnode-compat-require/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/transitive-bullshit","download_url":"https://codeload.github.com/transitive-bullshit/node-compat-require/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252569645,"owners_count":21769517,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backwards-compatible","cli","compatibility","node","nodejs","npx","version"],"created_at":"2024-10-03T13:20:31.159Z","updated_at":"2025-05-05T20:10:18.048Z","avatar_url":"https://github.com/transitive-bullshit.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# node-compat-require\n\n\u003e Easily allow your Node program to run in a target node version range to maximize compatibility.\n\n[![NPM](https://img.shields.io/npm/v/node-compat-require.svg)](https://www.npmjs.com/package/node-compat-require) [![Build Status](https://travis-ci.com/transitive-bullshit/node-compat-require.svg?branch=master)](https://travis-ci.com/transitive-bullshit/node-compat-require) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)\n\n- If unsupported node version, installs the right version with **npx** and continues.\n- **Targeted at CLIs** that want to maximize compatibility without sacrificing JS features.\n- Use **async / await** in older versions of node.\n- Optionally pin your node program to a **specific version** of node for extreme reproducibility.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"800\" alt=\"Demo\" src=\"https://cdn.rawgit.com/transitive-bullshit/node-compat-require/master/example/demo2.svg\"\u003e\n\u003c/p\u003e\n\n\n## Why\n\nA lot of Node.js CLI programs need to support older versions of Node, and in order to do so, they either:\n\n- Resort to using deprecated ES5 syntax and carefully make sure all dependencies follow suit.\n- Require the CLI to be run via Docker which is clumsy to execute (eg. no `npm install -g`).\n- Rely on a complicated transpilation step in order to achieve backwards compatibility.\n\nWhile transpilation is great for larger projects, it's a bit of a headache, when all you really want to do is ensure your program works for end users.\n\n\u003e `node-compat-require` is the simplest way of ensuring a compatible node version without sacrificing the latest \u0026 greatest node features.\n\n\n## Install\n\nThis module requires `node \u003e= 4`.\n\n```bash\nnpm install --save node-compat-require\n```\n\n\n## Usage\n\n```js\nconst compatRequire = require('node-compat-require')\n\ncompatRequire('.', { node: '\u003e= 8' })\n```\n\nIn this example, './index.js' would be required only once the Node process is `\u003e= 8`.\n\nSee the [example folder](https://github.com/transitive-bullshit/node-compat-require/tree/master/example) for a complete example of a node program which can be run with `node \u003e= 4` but will enforce `node \u003e= 8` at runtime in order to support newer JS features like async / await and object destructuring.\n\n\n## API\n\n### compatRequire(path, opts)\n\nIf the current node process satisfies the given requirements, returns `require(path)`.\n\nIf the current node process does not satisfy the requirements, installs the correct version of node, re-invokes the current node program as a subprocess, and exits once the child process exits.\n\n#### path\n\nType: `String`\n**Required**\n\nPath of file to require if node process satisfies constraints. This may be a relative file just like a normal node `require` statement.\n\n#### opts\n\nType: `Object`\n**Required**\n\n##### opts.node\n\nType: `String`\n**Required**\n\nRequired semver [range](https://www.npmjs.com/package/semver#ranges) for the node `process.version`.\n\nExamples:\n\n```js\ncompat('.', { node: '\u003e= 8' })\ncompat('./bin', { node: '^6' })\ncompat('./lib/cmd', { node: '9' })\ncompat('./example/cli', { node: '7.10.0' })\ncompat('.', { node: '4 || \u003e=9 || 6.0.0 - 7.0.0' })\n```\n\n##### opts.quiet\n\nType: `Boolean`\nDefault: `false`\n\nUse this to optionally silence the `npx` output.\n\n\n## How it works\n\nYou require `node-compat-require` and pass a desired node semver [range](https://www.npmjs.com/package/semver#ranges) (like `'\u003e= 8'` or `'^6.0.0'`).\n\nIf the current process's node version satisfies that range, then `node-compat-require` requires the target module and returns.\n\nIf the current process does not satisfy that range, then `npx` is used to temporarily install the appropriate matching version of [node](https://www.npmjs.com/package/node) from npm and re-run the current process as a subprocess using the temporary node executable. In this case, all commandline flags, environment variables, and stdio will be inherited from the current process. The child process will again run into `node-compat-require`, only this time it will require your target module normally because the version check is satisfied. Once the child process terminates, either due to successful completion or an error, `node-compat-require` will exit the parent process with the same exit code.\n\n**Note**: it is recommended but not required for you to invoke `node-compat-require` at the very beginning of your program.\n**Note**: `node-compat-require` needs an active internet connection for `npx` to install the correct version of node.\n\n\n## Related\n\n- [npx](https://github.com/zkat/npx) - Used under the hood to execute specific versions of node from npm.\n- [node](https://www.npmjs.com/package/node) - NPM package bundling different versions of node for different platforms.\n- [node language features](https://node.green/) - Breakdown of supported features across different versions of node.\n\n\n## License\n\nMIT © [Travis Fischer](https://github.com/transitive-bullshit)\n\nSupport my OSS work by \u003ca href=\"https://twitter.com/transitive_bs\"\u003efollowing me on twitter \u003cimg src=\"https://storage.googleapis.com/saasify-assets/twitter-logo.svg\" alt=\"twitter\" height=\"24px\" align=\"center\"\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransitive-bullshit%2Fnode-compat-require","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftransitive-bullshit%2Fnode-compat-require","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransitive-bullshit%2Fnode-compat-require/lists"}