{"id":17749472,"url":"https://github.com/oresoftware/r2g","last_synced_at":"2025-05-12T13:23:47.006Z","repository":{"id":32381756,"uuid":"132410861","full_name":"ORESoftware/r2g","owner":"ORESoftware","description":"▷ Test your package in the published format, without having to publish to NPM. ","archived":false,"fork":false,"pushed_at":"2022-12-26T00:59:54.000Z","size":501,"stargazers_count":60,"open_issues_count":26,"forks_count":5,"subscribers_count":6,"default_branch":"dev","last_synced_at":"2025-04-19T19:12:29.679Z","etag":null,"topics":["nodejs","npm","npm-pack","npm-publish","npm-test","tarball"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ORESoftware.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-07T05:23:05.000Z","updated_at":"2024-11-30T05:54:36.000Z","dependencies_parsed_at":"2023-01-14T21:04:42.630Z","dependency_job_id":null,"html_url":"https://github.com/ORESoftware/r2g","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORESoftware%2Fr2g","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORESoftware%2Fr2g/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORESoftware%2Fr2g/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ORESoftware%2Fr2g/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ORESoftware","download_url":"https://codeload.github.com/ORESoftware/r2g/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253745550,"owners_count":21957398,"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":["nodejs","npm","npm-pack","npm-publish","npm-test","tarball"],"created_at":"2024-10-26T11:23:28.189Z","updated_at":"2025-05-12T13:23:46.977Z","avatar_url":"https://github.com/ORESoftware.png","language":"TypeScript","readme":"\n\u003cimg width=\"200px\" align=\"right\" src=\"https://raw.githubusercontent.com/oresoftware/media/master/namespaces/r2g/oresoftware-r2g-rounded.png?foo\"\u003e\n\n[\u003cimg src=\"https://img.shields.io/badge/slack-@oresoftware/r2g-yellowgreen.svg?logo=slack\"\u003e](https://oresoftware.slack.com/messages/CCAHLN77B)\n\n[![Gitter](https://badges.gitter.im/oresoftware/r2g.svg)](https://gitter.im/oresoftware/r2g?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge)\n[![Version](https://img.shields.io/npm/v/r2g.svg?colorB=green)](https://www.npmjs.com/package/r2g)\n\n\u003cbr\u003e\n\n#  @oresoftware/r2g \n\n\u003e\n\u003e Properly test your NPM packages before publishing. \u003cbr\u003e\n\u003e This CLI tool allows you to easily test your package in the published format, without having to publish to an NPM registry.\n\n\u003cbr\u003e\n\n#### Caveats + Disclaimer\n\n\u003e\n\u003e This will not work with MS Windows. Only MacOS and *nix. \n\u003e If you are interested in getting to work on Windows, pls file a ticket.\n\u003e\n\n\u003cbr\u003e\n\n## Video demo\n\nWatch this video to learn how to use r2g: TBD (video demo coming in the future) \u003cbr\u003e\n\nThe video will reference this example repo: \u003cbr\u003e\nhttps://github.com/ORESoftware/r2g.example\n\n\u003cbr\u003e\n\n### Installation\n\n```console\n$ npm i -g r2g\n```\n\nYou can add the following to your ~/.bashrc and/or ~/.bash_profile files:\n\n```shell\n. \"$HOME/.oresoftware/shell.sh\"\n```\n\n\u003ci\u003e =\u003e Note you will also get bash completion for r2g, if you source the above shell script. \u003c/i\u003e\n\n\u003cbr\u003e\n_____________________________________________________________________________________________\n\n### FAQ\n\nsee docs/faq.md\n\n\u003cbr\u003e\n\n### About The Tool\n\nr2g tests your package after using `npm pack` and `npm install --production`. You can use your current test suite for testing, and also write some new smoke tests\nthat are specific to r2g. r2g current has 3 \u003ci\u003ephases\u003c/i\u003e, each phase is optional:\n\n\u003cbr\u003e\n\n* \u003cb\u003e phase-Z:\u003c/b\u003e packs your project and installs the packed project as a dependency of itself then runs `npm test` on your project. You can override `npm test` with `r2g.test` in package.json.\n* \u003cb\u003e phase-S:\u003c/b\u003e installs your project as a dependency of a dummy package in `$HOME/.r2g/temp/project`, then it executes the `r2gSmokeTest` function exported from your main.\n* \u003cb\u003e phase-T:\u003c/b\u003e Copies the test scripts from `.r2g/tests` in your project, to `$HOME/.r2g/temp/project/tests`, and runs them.\n\n\u003cbr\u003e\n\nBy default all phases are run, but you can skip phases with the `--skip=z,s,t` option.\n\n\u003cbr\u003e\n\nr2g is one of several tools that makes managing multiple locally developed NPM packages easier.\n\n\u003cb\u003e The current pieces are: \u003c/b\u003e\n\n* [npm-link-up (NLU)](https://github.com/ORESoftware/npm-link-up) =\u003e links multiple NPM packages together for local development\n* [r2g](https://github.com/ORESoftware/r2g) =\u003e tests local packages \u003ci\u003eproperly\u003c/i\u003e before publishing to NPM\n* [npp](https://github.com/ORESoftware/npp) =\u003e publish multiple packages and sync their semver versions\n\n\u003cbr\u003e\n\n## Quick reference\n\n\u003cbr\u003e\n\n\u003e\n\u003e```console\n\u003e$ r2g run  ### note: `r2g test` is an alias of `r2g run`\n\u003e```\n\u003e\n\u003e * Runs the tool, and runs all phases.\n\u003e\n\n\u003cbr\u003e\n\n\u003e\n\u003e```console\n\u003e$ r2g run --skip=z,s\n\u003e```\n\u003e\n\u003e * This will skip phases Z and S\n\u003e\n\n\u003cbr\u003e\n\n\u003e\n\u003e```console\n\u003e$ r2g run -z -s\n\u003e```\n\u003e\n\u003e * This will also skip phases Z and S\n\u003e\n\n\u003cbr\u003e\n\n\u003e\n\u003e```console\n\u003e$ r2g run --full\n\u003e```\n\u003e\n\u003e * Installs other locally developed dependencies to your main package, defined in `.r2g/config.js`, and tests everything together\n\u003e\n\n\u003cbr\u003e\n\n\u003e\n\u003e```console\n\u003e$ r2g run --full --pack\n\u003e```\n\u003e\n\u003e * Installs other locally developed dependencies to your main package, *npm packs them too*, and tests everything together\n\u003e\n\n\u003cbr\u003e\n\n\u003e\n\u003e```console\n\u003e$ r2g inspect\n\u003e```\n\u003e\n\u003e * Copies your project to a temp folder and logs info about a temp tarball that gets created\n\u003e * AKA, you can see which contents/folders/files will get included in the tarball\n\u003e * Also warns you about any especially large files that you may have accidentally included.\n\u003e\n\n\u003cbr\u003e\n\n\u003e\n\u003e```console\n\u003e$ r2g publish\n\u003e```\n\u003e\n\u003e * Publish your package and ignore the .r2g folder for an even leaner tarball\n\u003e * Copies your project to a temp folder and the .r2g folder is excluded/ignored\n\u003e * Also copies symlinks so you can include symlinked files/folders easily when publishing\n\u003e\n\n\u003cbr\u003e\n\n\n### Important Info\n\n* This tool is only proven on MacOS/*nix, not tested on Windows. If you do Windows and want something to do - fork this and make it work for Windows - it won't be hard.\n* You can use r2g with zero-config, depending on what you want to do.\n* Testing does not happen in your local codebase - before anything, your codebase is copied to `\"$HOME/.r2g/temp/copy\"`, and all writes happen within `\"$HOME/.r2g/temp\"`.\n* If you use the `--full` option, the local deps of your package will copied to: `\"$HOME/.r2g/temp/deps\"`\n* You can and should put your regular tests in `.npmignore`, but your .r2g folder should not be in `.npmignore`\n\n\u003cb\u003eTo make this README as clear and concise as possible:\u003c/b\u003e\n\n* Your NPM package is referred to as `X`. X is the name of the package you publish to NPM, which is the \"name\" field of your package.json.\n* The package.json file for X is simply referred to as `X-package.json`.\n* Your index.js file (or whatever the \"main\" property points to in X-package.json), is referred to as `X-main`\n\n\u003cbr\u003e\n\n______________________________________________________________________________________________\n\n## Purpose\n\nThis tool \u003ci\u003ecomplements\u003c/i\u003e your standard CI/CD testing for NPM libraries. You might already be using Travis, CircleCI, etc, to test your library\nwhen you do a `git push`. Keep doing that. \u003ci\u003eHowever, what you are already doing is likely to be insufficient because:\u003c/i\u003e\n\n1. You install using `npm install` instead of `npm install --production`, because you need your devDependencies for your tests. (whoops!).\n2. You are testing your package directly, instead of testing it as a dependency of another project. In reality, someone will be using your package via `node_modules/X`, and for example, your postinstall routine may behave differently here.\n3. You are not using `npm pack` to package your project before testing it. Your [`.npmignore`](https://docs.npmjs.com/misc/developers#keeping-files-out-of-your-package)  file could mean you will be missing files, when someone goes to use your package in the wild. Likewise, if\nthe [\"files\"](https://docs.npmjs.com/files/package.json#files) property in X-package.json is too passive, you might be missing files as well. Using `npm pack` before testing solves that.\n4. It is possible to check out a branch that has passed on a remote CI/CD platform but locally does not have the built/transpiled target files. This means the files will not make it into the tarball that gets published to NPM. \nTesting with r2g locally before publishing a local branch means you avoid this problem, because if the target files are not built, r2g tests will fail.\n\nThe above things are why you need to take some extra pre-cautions before publishing NPM packages. I think everyone has had an `.npmignore` file that accidentally ignored files we need in production.\nAnd we have all had dependencies listed in devDependencies instead of dependencies, which caused problems when people try to use the library. Those are the motivations for using this tool,\nto *prove* that X works in its final format.\n\n* There is a secret feature which is extremely badass - install other locally developed packages which are dependencies of X, as part of r2g testing.\nSee \"Linking with existing local dependencies\" below.\n\n\u003cbr\u003e\n\n### How it works in detail\nTo learn more about how r2g works in detail, see: `docs/r2g-runtime-steps.md`\n\n\u003cbr\u003e\n\n# Basic usage / Getting started\n\nYou can use r2g with zero-config - you just need to implement a single function. \n\n\u003cbr\u003e\n\nTo start, execute this in a shell at the root of your project:\n\n```bash\n$ r2g run\n```\n\nThis command will then fail. That's expected. \n\n\u003cbr\u003e\n\nTo get your test to pass, add this to X-main (your package's index file, whatever \"main\" in package.json points to):\n\n```js\nexports.r2gSmokeTest = async () =\u003e { \n  return Promise.resolve(true);\n};\n```\n\nthe above function is called with `Promise.resolve(X.r2gSmokeTest())`, and in order to pass it must resolve to `true` (not just truthy). \n\n\u003cbr\u003e\n\n\u003cb\u003eTo read more about the exported r2gSmokeTest function, see:\u003c/b\u003e `docs/r2g-smoke-test-exported-main-function.md`\n\n\u003cbr\u003e\n\nNote: the exported function `r2gSmokeTest` allows you to smoke test your package. When this function is run you \u003ci\u003emay\u003c/i\u003e use the production dependencies declared in your project.\n\u003ci\u003e However, for other r2g tests, you may *not* directly use the dependencies declared in X-package.json, *you may only require X itself*. \u003c/i\u003e\n\n\u003cbr\u003e\n\n## Adding more tests beyond the `r2gSmokeTest` function\n\nTo do more sophisticated tests, we add some configuration in a folder called .r2g in the root of your project. \n\n\u003cbr\u003e\n\nTo do this, run:\n\n```bash\nr2g init\n```\n\nthis will add a folder to your project called `.r2g`. Your `.r2g` folder should never be in `.npmignore`. (Running `r2g init` is safe, it will not overwrite any existing files).\nYour new `.r2g` folder contains a file called: `.r2g/smoke-test.js`.\n\n\u003cbr\u003e\n\nNow when `r2g run` executes, it will run `.r2g/smoke-test.js`,  *but* it will run this test in the context of the main project, meaning it will copy: \n\n\u003cbr\u003e\n\n   `$HOME/.r2g/temp/project/node_modules/X/.r2g/smoke-test.js` --\u003e  `$HOME/.r2g/temp/project/smoke-test.js`\n\n\u003cbr\u003e\n\nThe above is very important to understand, because it means that this smoke test *should not include any dependencies* from X-package.json.\nIn fact, the *only* dependency `.r2g/smoke-test.js` should require, besides core modules, is X itself.\n\n\u003cbr\u003e\n\n## Linking with existing local dependencies:\n\nRun `r2g init` and in your `.r2g/config.js` file, add local package names to the packages property:\n\n```js\nexports.default = {\n\n  // ...\n\n  packages: {\n     // local packages will be installed to your project --\u003e test your local dependencies instead of installing from NPM\n     'your-local-package-b': true,\n     'your-local-package-c': true\n   }\n}\n```\n\nIf you execute `r2g run --full` these packages (b,c) will be *discovered* on your local fs, and copied to `\"$HOME/.r2g/temp/deps/*\"`, and then X's package.json will look like this:\n\n```json\n{\n  \"dependencies\": {\n   \"your-local-package-b\": \"file:///home/user/.r2g/temp/deps/your-local-package-b\",\n   \"your-local-package-c\": \"file:///home/user/.r2g/temp/deps/your-local-package-c\",\n  }\n}\n```\n\nIf you execute `r2g run --full --pack`, then this awesomeness happens:\n\n\n```json\n{\n  \"dependencies\": {\n   \"your-local-package-b\": \"file:///home/user/.r2g/temp/deps/your-local-package-b.tgz\",\n   \"your-local-package-c\": \"file:///home/user/.r2g/temp/deps/your-local-package-c.tgz\",\n  }\n}\n```\n\nSo using `r2g run --full` =\u003e we install local deps instead of the deps from NPM. \n\n\u003cbr\u003e\n\nAnd using `r2g run --full --pack` =\u003e we pack the local deps before installing them. \n\n\u003cbr\u003e\n\nAwesome.\n\n\u003cb\u003eTo read more about using local deps for testing instead of installing your local deps from NPM, see:\u003c/b\u003e \u003cbr\u003e =\u003e `docs/r2g-using-local-deps.md`\n\n\u003cbr\u003e\n\n## Usage in a Docker image/container\n\nUse a Docker container for a fresh/independent/isolated testing env. For packages that do more complex/system things, it will be useful to use a locally running Docker container.\nTo use r2g in a Docker container, see: https://github.com/ORESoftware/r2g.docker\n\n\u003cbr\u003e\n\nAlternatively, you can just run r2g as part of your normal CI/CD library testing on remote servers.\nFirst, make sure you have Docker installed on your local machine. See standard installation instructions for MacOS/*nix.\n\n\u003cbr\u003e\n\nRun this in the root of your project:\n\n```bash\n$ r2g init --docker  # you only need to run this once per project, but won't hurt if you do it more than once\n```\n\nThen run this:\n\n```bash\n$ r2g docker\n```\n\nThe above command actually uses this command line tool: \u003cbr\u003e\nhttps://github.com/ORESoftware/r2g.docker\n\n\n\u003cbr\u003e\n\n### For the future:\n\n* Instead a dummy NPM project which will depend on X, we can allow users to use their own test projects, and pull those in with `git clone` or what not.\n\n\n### TBD\nJust adding some spaces here\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foresoftware%2Fr2g","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foresoftware%2Fr2g","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foresoftware%2Fr2g/lists"}