{"id":14263249,"url":"https://github.com/pkgxdev/dev","last_synced_at":"2025-04-10T04:07:15.512Z","repository":{"id":197292176,"uuid":"695534535","full_name":"pkgxdev/dev","owner":"pkgxdev","description":"isolated `dev` environments","archived":false,"fork":false,"pushed_at":"2025-04-09T13:47:50.000Z","size":72,"stargazers_count":24,"open_issues_count":22,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-10T04:07:09.848Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pkgxdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-23T13:39:01.000Z","updated_at":"2025-04-09T13:47:45.000Z","dependencies_parsed_at":"2024-08-22T13:13:26.265Z","dependency_job_id":"6ffc0143-2eb2-42a5-a6d3-818b94f3467c","html_url":"https://github.com/pkgxdev/dev","commit_stats":null,"previous_names":["pkgxdev/dev"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkgxdev%2Fdev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkgxdev%2Fdev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkgxdev%2Fdev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkgxdev%2Fdev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pkgxdev","download_url":"https://codeload.github.com/pkgxdev/dev/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248154984,"owners_count":21056543,"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":[],"created_at":"2024-08-22T13:04:46.882Z","updated_at":"2025-04-10T04:07:15.501Z","avatar_url":"https://github.com/pkgxdev.png","language":"TypeScript","funding_links":[],"categories":["others"],"sub_categories":[],"readme":"# `dev`\n\n`dev` uses `pkgx` and shellcode to automatically, install and activate the\npackages you need for different projects as you navigate in your shell.\n\nEnsure you are using the same versions of tools for your entire stack, during\ndev, across your team and in production.\n\n\u003e [!NOTE]\n\u003e Packages are installed to `~/.pkgx` and not available to your wider system\n\u003e without using a tool from the `pkgx` tooling ecosystem.\n\n## Getting Started\n\nSince `dev` v1.8.0 we integrate with `pkgm` (^0.11) and this is the recommended\nway to use `dev`.\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e Both `dev` and the packages you want to be `dev`-aware must be installed to\n\u003e `/usr/local/` for this to work. (`dev` (but only `dev`) can be a `pkgm shim`).\n\u003e\n\u003e ```sh\n\u003e sudo pkgm install dev node@22\n\u003e ```\n\n```sh\n$ cd my-project\n$ ls\npackage.json\n\n$ node --version\ncommand not found: node\n\n$ sudo pkgm install dev node\n$ node --version \u0026\u0026 which node\nv23.11.0\n/usr/local/bin/node\n\n$ cat package.json | jq .engines\n{\n  \"node\": \"^20\"\n}\n\n$ dev .\nactivated `~/my-project` (+node^20)\n\n$ node --version \u0026\u0026 which node\nv20.19.0\n/usr/local/bin/node\n\n$ cd ..\n$ node --version \u0026\u0026 which node\nv23.11.0\n/usr/local/bin/node\n\n$ cd -\n$ node --version \u0026\u0026 which node\nv20.19.0\n/usr/local/bin/node\n```\n\n`pkgm` installs `dev`-aware packages to `/usr/local/bin`. Provided you have\n`/usr/local/bin/dev` installed and you have activated `dev` in your project\ndirectories the `node` that is invoked is swapped out _when invoked_.\n\nThis is the recommended way to use `dev` because it works everywhere and not\njust the terminal.\n\n## `dev` via Shellcode\n\nShellcode works _as well_ and is your preference. It has notable caveats with\nregard to use in tools like editors. It also requires you to add shellcode to\nyour `shell.rc` files and thus is more intrusive (depending on your outlook).\n\nA great advantage of the shellcode is not needing to install tools you may never\nneed again when exploring new open source projects.\n\n```sh\npkgx dev integrate\n```\n\n`dev` requires `pkgx` but at your preference:\n\n```sh\nbrew install pkgxdev/made/dev\ndev integrate\n```\n\nWe support macOS \u0026 Linux, **Bash** \u0026 **Zsh**. PRs are very welcome to support\nmore shells.\n\n\u003e [!NOTE]\n\u003e\n\u003e `dev integrate` looks for and edits known `shell.rc` files adding one line:\n\u003e\n\u003e ```sh\n\u003e eval \"$(dev --shellcode)\"\n\u003e ```\n\u003e\n\u003e If you don’t trust us (good on you), then do a dry run first:\n\u003e\n\u003e ```sh\n\u003e pkgx dev integrate --dry-run\n\u003e ```\n\u003e\n\u003e If you like, preview the shellcode: `pkgx dev --shellcode`. This command only\n\u003e outputs shellcode, it doesn’t modify any files or do anything else either.\n\n### Usage\n\n```sh\n$ cd my-project\n\nmy-project $ ls\npackage.json\n\nmy-project $ dev\n+nodejs.org\n# ^^ installs node to ~/.pkgx/nodejs.org/v22.12.0 if not already installed\n\nmy-project $ node --version\nv22.12.0\n\n$ which node\n~/.pkgx/nodejs.org/v22.12.0/bin/node\n\n$ cd ..\n-nodejs.org\n\n$ node\ncommand not found: node\n```\n\n\u003e [!TIP]\n\u003e\n\u003e #### Try Before You `vi`\n\u003e\n\u003e Modifying your `shell.rc` can be… _intimidating_. If you just want to\n\u003e temporarily try `dev` out before you `:wq`—we got you:\n\u003e\n\u003e ```sh\n\u003e $ cd my-project\n\u003e $ eval \"$(pkgx dev)\"\n\u003e +deno^2\n\u003e $ deno --version\n\u003e deno 2.1.1\n\u003e ```\n\u003e\n\u003e The devenv will only exist for the duration of your shell session.\n\n## How Packages are Determined\n\n- We look at the files you have and figure out the packages you need.\n- Where possible we also determine the versions you need if such things can be\n  determined by looking at configuration files.\n\n## Specifying Versions\n\nWe allow you to add YAML front matter to all files to specify versions more\nprecisely:\n\n```toml\n# ---\n# pkgx:\n#   dependencies:\n#     openssl.org: 1.1.1n\n# ---\n\n[package]\nname = \"my cargo project\"\n# snip…\n```\n\nWe allow more terse expressions including eg:\n\n```toml\n# ---\n# pkgx:\n#   dependencies: openssl.org@1.1.1n deno^2 npm\n# ---\n```\n\nThe major exception being json since it doesn’t support comments, in this case\nwe read a special `pkgx` node:\n\n```json\n{\n  \"pkgx\": {\n    \"dependencies\": {\n      \"openssl.org\": \"1.1.1n\",\n      \"deno\": \"^2\",\n      \"npm\": null\n    }\n  }\n}\n```\n\nYou can also make a `pkgx.yaml` file.\n\n## Adding Custom Environment Variables\n\nYou can add your own environment variables if you like:\n\n```toml\n# ---\n# pkgx:\n#   dependencies:\n#     openssl.org: 1.1.1n\n#   env:\n#     MY_VAR: my-value\n# ---\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e - Adding environment variables only works via the `shellcode` route.\n\u003e - The environment variable's value is sanitized, so expressions like\n\u003e   `MY_VAR: $(sudo rm -rf --no-preserve-root /)` will throw an error.\n\u003e - We recommend `direnv` instead of this route.\n\n## `dev` \u0026 Editors\n\nThe sure fire way for things to work in editors is to use the `dev`/`pkgm`\ncombo. Having said this most editors if opened via the Terminal will inherit\nthat Terminal’s environment.\n\n## GitHub Actions\n\n```yaml\n- uses: pkgxdev/dev@v1\n```\n\nOur action installs needed packages (via `pkgx`) and sets up the environment the\nsame as `dev` does in your terminal.\n\n## Contributing\n\nWe use `deno`, so either install that or—you know—type `dev`.\n\nEdit [./src/sniff.ts](src/sniff.ts) to add new dev types.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkgxdev%2Fdev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpkgxdev%2Fdev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkgxdev%2Fdev/lists"}