0
# Package Management
1

2
Tools for analyzing, filtering, and managing packages within your monorepo structure, including package listing and workspace pruning functionality.
3

4
## Capabilities
5

6
### List Packages
7

8
List and analyze packages in your monorepo with flexible filtering and output options.
9

10
```bash { .api }
11
turbo ls [packages...] [options]
12

13
# List all packages
14
turbo ls
15

16
# List specific packages with details
17
turbo ls @myorg/web-app @myorg/api
18

19
# List only affected packages
20
turbo ls --affected
21

22
# List packages matching filter
23
turbo ls --filter="@myorg/*"
24
```
25

26
**List Options:**
27

28
```bash { .api }
29
# Package filtering
30
--affected                         # Show only packages affected by changes
31
--filter <selector> / -F           # Package selector (pnpm syntax)
32

33
# Output formatting
34
--output <format>                  # Output format (pretty|json)
35
```
36

37
**Usage Examples:**
38

39
```bash
40
# List all packages in human-readable format
41
turbo ls
42

43
# List packages as JSON for programmatic use
44
turbo ls --output=json
45

46
# Show only packages affected by changes since main branch
47
turbo ls --affected
48

49
# List packages in a specific scope
50
turbo ls --filter="@myorg/*"
51

52
# Get details about specific packages
53
turbo ls web-app ui-lib --output=json
54
```
55

56
### Prune Workspace
57

58
Create a subset of your monorepo containing only the specified packages and their dependencies.
59

60
```bash { .api }
61
turbo prune <scope> [options]
62

63
# Prune to specific package
64
turbo prune @myorg/web-app
65

66
# Prune multiple packages
67
turbo prune @myorg/web-app @myorg/api
68

69
# Prune for Docker deployment
70
turbo prune @myorg/web-app --docker
71
```
72

73
**Prune Options:**
74

75
```bash { .api }
76
# Output configuration
77
--out-dir <path>                   # Output directory (default: "out")
78

79
# Docker optimization
80
--docker                           # Enable Docker-optimized output
81

82
# File handling
83
--use-gitignore <bool>             # Respect .gitignore when copying (default: true)
84
```
85

86
**Usage Examples:**
87

88
```bash
89
# Create subset for web app deployment
90
turbo prune @myorg/web-app --out-dir=deploy
91

92
# Prune for Docker with optimized layer structure
93
turbo prune @myorg/api --docker --out-dir=docker-context
94

95
# Prune without respecting .gitignore
96
turbo prune @myorg/web-app --use-gitignore=false
97

98
# Prune multiple related packages
99
turbo prune @myorg/web-app @myorg/shared-lib
100
```
101

102
### Package Filtering
103

104
Advanced package selection using pnpm-style selectors for precise targeting.
105

106
```bash { .api }
107
# Filter syntax patterns
108
--filter="<package-name>"          # Exact package name
109
--filter="@scope/*"                # All packages in scope
110
--filter="./apps/*"                # Packages in directory
111
--filter="...@myorg/web-app"       # Package and its dependencies
112
--filter="@myorg/web-app..."       # Package and its dependents
113
--filter="...[HEAD~1]"             # Changed packages since commit
114
--filter="...{./apps/web}"         # Dependencies of package in directory
115
```
116

117
**Filter Examples:**
118

119
```bash
120
# Select specific package
121
turbo run build --filter="@myorg/web-app"
122

123
# Select all packages in apps directory
124
turbo run build --filter="./apps/*"
125

126
# Select package and all its dependencies
127
turbo run build --filter="...@myorg/web-app"
128

129
# Select package and all its dependents
130
turbo run build --filter="@myorg/shared-lib..."
131

132
# Select only changed packages
133
turbo run test --filter="...[HEAD~1]"
134

135
# Combine multiple filters
136
turbo run build --filter="@myorg/*" --filter="!@myorg/old-*"
137
```
138

139
### Affected Package Detection
140

141
Automatically detect which packages have changed and need to be rebuilt or tested.
142

143
```bash { .api }
144
# Affected package options
145
--affected                         # Only include affected packages
146

147
# Works with most commands
148
turbo run build --affected
149
turbo run test --affected  
150
turbo ls --affected
151
```
152

153
**Usage Examples:**
154

155
```bash
156
# Run tests only for affected packages
157
turbo run test --affected
158

159
# Build only what has changed
160
turbo run build --affected
161

162
# List affected packages for review
163
turbo ls --affected --output=json
164
```
165

166
## Package Information Types
167

168
```typescript { .api }
169
interface PackageInfo {
170
  name: string;
171
  version: string;
172
  path: string;
173
  packageJson: PackageJson;
174
  dependencies: string[];
175
  devDependencies: string[];
176
  scripts: Record<string, string>;
177
}
178

179
interface PackageJson {
180
  name: string;
181
  version: string;
182
  scripts?: Record<string, string>;
183
  dependencies?: Record<string, string>;
184
  devDependencies?: Record<string, string>;
185
  peerDependencies?: Record<string, string>;
186
  workspaces?: string[] | WorkspaceConfig;
187
}
188

189
interface WorkspaceConfig {
190
  packages: string[];
191
  nohoist?: string[];
192
}
193

194
interface PruneOptions {
195
  scope: string[];
196
  docker: boolean;
197
  output_dir: string;
198
  use_gitignore: boolean;
199
}
200

201
interface ListOptions {
202
  packages: string[];
203
  affected: boolean;
204
  filter: string[];
205
  output: "pretty" | "json";
206
}
207
```