0
# Package Management
1

2
npm installation and package management functionality including npm setup, requirements file processing, and package installation with version management.
3

4
## Capabilities
5

6
### npm Installation
7

8
Installs npm package manager in the Node.js virtual environment with platform-specific optimizations.
9

10
```python { .api }
11
def install_npm(env_dir, _src_dir, args):
12
    """
13
    Install npm package manager in Node.js environment.
14
    
15
    Parameters:
16
    env_dir (str): Environment directory path
17
    _src_dir (str): Source directory (unused in current implementation)
18
    args (argparse.Namespace): Configuration arguments
19
    
20
    Installs npm using the version specified in args.npm:
21
    - 'latest' for most recent npm version
22
    - Specific version number (e.g., '8.19.0')
23
    - Downloads and configures npm for the environment
24
    - Sets up proper npm configuration and cache directories
25
    """
26
```
27

28
### Windows npm Installation
29

30
Platform-specific npm installation function optimized for Windows environments.
31

32
```python { .api }
33
def install_npm_win(env_dir, src_dir, args):
34
    """
35
    Install npm on Windows platforms with Windows-specific handling.
36
    
37
    Parameters:
38
    env_dir (str): Environment directory path
39
    src_dir (str): Source/download directory
40
    args (argparse.Namespace): Configuration arguments
41
    
42
    Handles Windows-specific npm installation requirements:
43
    - Windows path separators and executable extensions
44
    - npm.cmd and npm batch file setup
45
    - Windows registry and environment variable configuration
46
    - PowerShell execution policy considerations
47
    """
48
```
49

50
### Package Installation from Requirements
51

52
Installs npm packages from requirements files, similar to pip's requirements.txt functionality.
53

54
```python { .api }
55
def install_packages(env_dir, args):
56
    """
57
    Install npm packages from requirements file.
58
    
59
    Parameters:
60
    env_dir (str): Environment directory path
61
    args (argparse.Namespace): Configuration arguments containing requirements file path
62
    
63
    Processes requirements file containing package specifications:
64
    - Package names with specific versions (e.g., 'express@4.18.0')
65
    - Package names with version ranges
66
    - Git repository URLs
67
    - Local file paths
68
    
69
    Requirements file format example:
70
    express@4.18.0
71
    lodash@^4.17.21
72
    moment@>=2.29.0
73
    
74
    Installs packages globally within the Node.js environment
75
    and handles dependency resolution and version conflicts.
76
    """
77
```
78

79
## Shell Functions
80

81
The activation scripts created by nodeenv include built-in package management functions:
82

83
### freeze Function
84

85
The freeze function is available in activated environments and provides functionality similar to pip freeze.
86

87
```bash { .api }
88
# In bash/zsh environments
89
freeze [output_file]
90

91
# List installed packages
92
freeze
93

94
# Save to requirements file  
95
freeze requirements.txt
96

97
# List local packages only
98
freeze -l requirements.txt
99
```
100

101
```fish { .api }
102
# In fish shell environments
103
freeze [output_file]
104

105
# List installed packages
106
freeze
107

108
# Save to requirements file
109
freeze requirements.txt
110

111
# List local packages only  
112
freeze -l requirements.txt
113
```
114

115
The freeze function:
116
- Lists all globally installed npm packages in the environment
117
- Outputs package names with exact version numbers
118
- Supports saving to requirements files for environment reproduction
119
- Provides local package listing with `-l` flag
120
- Compatible with requirements file format for `--requirements` option
121

122
## Usage Examples
123

124
### Install npm with Specific Version
125

126
```python
127
import nodeenv
128
from argparse import Namespace
129

130
args = Namespace(
131
    npm='8.19.0',  # Specific npm version
132
    with_npm=True
133
)
134

135
nodeenv.install_npm('/path/to/env', '/tmp/src', args)
136
```
137

138
### Install Packages from Requirements File
139

140
```python
141
import nodeenv
142
from argparse import Namespace
143

144
# Create requirements.txt with content:
145
# express@4.18.0
146
# lodash@4.17.21
147
# moment@2.29.4
148

149
args = Namespace(
150
    requirements='/path/to/requirements.txt',
151
    jobs='2'
152
)
153

154
nodeenv.install_packages('/path/to/env', args)
155
```
156

157
### Complete Environment with Packages
158

159
```python
160
import nodeenv
161
from argparse import Namespace
162

163
# Create environment and install packages
164
args = Namespace(
165
    node='18.17.0',
166
    npm='9.8.0', 
167
    with_npm=True,
168
    requirements='/path/to/requirements.txt',
169
    jobs='4'
170
)
171

172
env_dir = '/path/to/myenv'
173
src_dir = '/tmp/nodeenv-src'
174

175
# Create environment
176
nodeenv.create_environment(env_dir, args)
177

178
# Packages are automatically installed if requirements file specified
179
```
180

181
### Using freeze in Activated Environment
182

183
```bash
184
# Activate environment
185
source myenv/bin/activate
186

187
# Install some packages
188
npm install -g express lodash moment
189

190
# List installed packages
191
freeze
192

193
# Output:
194
# express@4.18.2
195
# lodash@4.17.21  
196
# moment@2.29.4
197

198
# Save to requirements file
199
freeze requirements.txt
200

201
# Deactivate environment
202
deactivate_node
203
```