0
# Asset Management
1
2
CLI tools and utilities for managing compiled assets, including cleanup of orphaned files that are no longer referenced in Vite manifests.
3
4
## Capabilities
5
6
### Clean Orphaned Assets CLI
7
8
Command-line tool for removing orphaned assets that are no longer referenced in the Vite manifest files.
9
10
```bash { .api }
11
# Basic usage
12
clean-orphaned-assets
13
14
# With custom manifest path
15
clean-orphaned-assets --manifest=./custom/path/manifest.json
16
17
# For SSR builds
18
clean-orphaned-assets --ssr
19
20
# With custom assets directory
21
clean-orphaned-assets --assets=./public/assets
22
23
# Dry run to see what would be removed
24
clean-orphaned-assets --dry-run
25
26
# Quiet mode (suppress output)
27
clean-orphaned-assets --quiet
28
```
29
30
### CLI Options
31
32
Complete command-line options for the asset cleanup tool:
33
34
```bash { .api }
35
--manifest=<path> # Specify custom manifest file path
36
--ssr # Use SSR manifest file locations
37
--assets=<path> # Specify custom assets directory path
38
--dry-run # Preview what would be removed without deleting
39
--quiet # Suppress all output messages
40
```
41
42
**Default Behavior:**
43
44
- **Regular builds**: Looks for `./public/build/manifest.json`
45
- **SSR builds**: Looks for `./bootstrap/ssr/ssr-manifest.json` and `./bootstrap/ssr/manifest.json`
46
- **Assets directory**: Uses manifest directory + `/assets` (e.g., `./public/build/assets`)
47
48
**Usage Examples:**
49
50
```bash
51
# Clean regular build assets
52
clean-orphaned-assets
53
54
# Clean SSR build assets
55
clean-orphaned-assets --ssr
56
57
# Preview what would be cleaned without actually deleting
58
clean-orphaned-assets --dry-run
59
60
# Clean with custom paths
61
clean-orphaned-assets \
62
--manifest=./dist/manifest.json \
63
--assets=./dist/assets
64
65
# Silent cleanup for CI/CD scripts
66
clean-orphaned-assets --quiet
67
```
68
69
## Manifest Processing
70
71
The asset cleanup tool processes different types of Vite manifests:
72
73
### Regular Build Manifest
74
75
Standard Vite manifest format with asset references:
76
77
```json
78
{
79
"resources/js/app.js": {
80
"file": "assets/app-abc123.js",
81
"src": "resources/js/app.js",
82
"isEntry": true,
83
"css": ["assets/app-def456.css"]
84
}
85
}
86
```
87
88
### SSR Manifest
89
90
Server-side rendering manifest with array format:
91
92
```json
93
{
94
"resources/js/ssr.js": [
95
"assets/ssr-abc123.js",
96
"assets/shared-def456.js"
97
]
98
}
99
```
100
101
## Asset Detection Logic
102
103
The cleanup process follows these steps:
104
105
1. **Locate Manifest**: Find the appropriate manifest file based on options
106
2. **Parse Manifest**: Extract all referenced asset files from the manifest
107
3. **Scan Assets Directory**: List all files in the assets directory
108
4. **Identify Orphans**: Compare assets directory files against manifest references
109
5. **Remove Orphans**: Delete files not referenced in the manifest (unless dry-run)
110
111
## Integration with Build Process
112
113
The asset cleanup tool can be integrated into your build workflow:
114
115
### Package.json Scripts
116
117
```json
118
{
119
"scripts": {
120
"build": "vite build",
121
"build:clean": "vite build && clean-orphaned-assets",
122
"build:ssr": "vite build --ssr && clean-orphaned-assets --ssr",
123
"clean:assets": "clean-orphaned-assets",
124
"clean:preview": "clean-orphaned-assets --dry-run"
125
}
126
}
127
```
128
129
### CI/CD Integration
130
131
```bash
132
#!/bin/bash
133
# Build assets
134
npm run build
135
136
# Clean orphaned assets quietly
137
clean-orphaned-assets --quiet
138
139
# Verify build completed successfully
140
if [ $? -eq 0 ]; then
141
echo "Build and cleanup completed successfully"
142
else
143
echo "Build or cleanup failed"
144
exit 1
145
fi
146
```
147
148
## Safety Features
149
150
The cleanup tool includes several safety mechanisms:
151
152
- **Dry Run Mode**: Preview changes without making modifications
153
- **Manifest Validation**: Ensures manifest file exists and is valid JSON
154
- **Path Validation**: Verifies assets directory exists before scanning
155
- **Error Handling**: Graceful handling of file system errors
156
- **Logging**: Detailed output of operations performed (unless quiet mode)
157
158
## Output Examples
159
160
### Normal Operation
161
162
```
163
Reading manifest [./public/build/manifest.json].
164
Non-SSR manifest found.
165
Verify assets in [./public/build/assets].
166
[3] orphaned assets found.
167
Removing orphaned asset [./public/build/assets/old-file-123.js].
168
Removing orphaned asset [./public/build/assets/unused-456.css].
169
Removing orphaned asset [./public/build/assets/legacy-789.png].
170
```
171
172
### Dry Run Mode
173
174
```
175
Reading manifest [./public/build/manifest.json].
176
Non-SSR manifest found.
177
Verify assets in [./public/build/assets].
178
[2] orphaned assets found.
179
Orphaned asset [./public/build/assets/old-file-123.js] would be removed.
180
Orphaned asset [./public/build/assets/unused-456.css] would be removed.
181
```
182
183
### No Orphaned Assets
184
185
```
186
Reading manifest [./public/build/manifest.json].
187
Non-SSR manifest found.
188
Verify assets in [./public/build/assets].
189
No orphaned assets found.
190
```