npmenv 0.2.0
A wrapper for npm that stores node_modules outside of project and provides easy access to them.
License: MIT
Requires Python: ~=3.6

# npmenv

A wrapper for npm that stores node_modules outside of project and provides easy access to them.

`npmenv` is a Python module inspired by `pipenv` in that it stores packages outside of projects (in an OS-specific dir) to avoid cluttering projects. It also has a `run` command that puts `node_modules/.bin` in `PATH` before running the given command. If you `install node` in a project then it will have the added benefit of using that node version to run your code and third-party scripts. You can then lock down your node version per-project and upgrade them individually when desired.

__Install:__ `pip install npmenv`\
__Supports:__ All platforms (Linux, MacOS, Windows)\
__Requires:__ Python 3.6+

[PyPI package](https://pypi.org/project/npmenv/) | [Source](https://github.com/shadow-light/npmenv)


## How it works

Aside from `env-...` commands, npmenv hands over to `npm`. But before handing over, it symlinks your `package.json` and/or `package-lock.json` into the virtual environment and runs npm in that environment. You can access any `node_modules` files via the path returned by `npmenv env-location`, which will stay the same even if the environment is removed and recreated (though not if your project path changes).

__Note:__ npmenv does not handle any other files generated by npm (such as shrinkwrap), though more features may be added in future.


## CLI usage
```
npmenv 0.2.0

env-list            List all currently existing environments
env-location        Output path to env for current dir (may not exist yet)
env-modules [name]  List items in node_modules (recursive if package name given)
env-run cmd [args]  Run command with env's bin dir in start of PATH
env-rm [env_id]     Remove the env for current dir (or env with given id)
env-cleanup         Remove envs for projects that no longer exist
*any npm command*
```

## Module API
```
class NpmenvException(builtins.Exception)
    Exception for npmenv-related issues

env_cleanup() -> List[Tuple[str, pathlib.Path, str]]
    Remove envs for projects that no longer exist (no package or lock file)

env_list() -> List[Tuple[str, pathlib.Path, Union[str, NoneType]]]
    Return list of tuples (env id, project dir, issue with project existance)

env_location(proj_dir:Union[pathlib.Path, str]=None) -> pathlib.Path
    Return env dir path for given project dir (may/may not exist yet)

env_npm(args:str='', proj_dir:Union[pathlib.Path, str]=None) -> subprocess.CompletedProcess
    Execute npm with given args in env dir of given project dir

env_rm(identifier:Union[pathlib.Path, str]=None) -> pathlib.Path
    Remove the env for given project dir or env id (defaults to CWD)

env_run(args:str, proj_dir:Union[pathlib.Path, str]=None, run_kwargs:Any={}) -> subprocess.CompletedProcess
    Run a command with node_modules/.bin at start of PATH environment variable

```

## Version history
```
0.2.0           Added run_kwargs arg to env_run
0.1.2           Added env-modules command
0.0.2           Improved typing support (no functional changes)
0.0.1           Improved documentation (no functional changes)
0.0.0           Version 0.0.0
```