packlyze 3.0.3 → 3.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,387 +1,394 @@
1
- # Packlyze
2
-
3
- [![NPM Version](https://img.shields.io/npm/v/packlyze.svg)](https://www.npmjs.com/package/packlyze)
4
- [![Build Status](https://img.shields.io/github/workflow/status/iamabhshk/Packlyze/CI)](https://github.com/iamabhshk/Packlyze/actions)
5
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
-
7
- ## Packlyze
8
-
9
- Advanced bundle analyzer with insights, recommendations, historical tracking, and a sleek HTML report.
10
-
11
- ## 📊 Features
12
-
13
- - **Package Analysis**: Parse and analyze webpack, rollup, and esbuild stats files.
14
- - **Package-Level Insights**: Group modules by npm package to identify heavy dependencies.
15
- - **Smart Recommendations**: Suggestions to optimize bundle size and structure.
16
- - **Tree-Shaking Detection**: Identify modules and patterns that block tree-shaking.
17
- - **Duplicate Detection**: Find and quantify duplicate modules with potential savings.
18
- - **Chunk Analysis**: Analyze code-splitting efficiency and get optimization recommendations.
19
- - **Unused Code Detection**: Identify potentially unused modules in your bundle.
20
- - **Historical Tracking**: Track bundle size trends over time with `packlyze trends`.
21
- - **Dependency Graph**: Generate Graphviz DOT files to visualize module dependencies.
22
- - **Beautiful HTML Report**: Sleek, dark-themed, interactive report with search, filter, and sort.
23
- - **Baseline Comparison**: Compare current vs previous stats to see regressions and improvements.
24
- - **Multiple Export Formats**: Export to HTML, CSV, or Markdown.
25
- - **Config File Support**: Use `.packlyzerc` or `packlyze.config.json` for project defaults.
26
- - **CLI Tool**: Easy-to-use command-line interface with filters and CI-friendly thresholds.
27
- - **Brotli Estimates**: Get Brotli compression size estimates (17% smaller than gzip).
28
- - **TypeScript Ready**: Full TypeScript support with type definitions.
29
-
30
- ## 🚀 Quick Start
31
-
32
- Packlyze can be used in two main ways: as a CLI tool and as a Node.js/TypeScript library.
33
-
34
- **1. Install Packlyze (globally or with npx):**
35
-
36
- You can install Packlyze globally or use it via npx:
37
-
38
- ```bash
39
- npm install -g packlyze
40
- # or
41
- npx packlyze --help
42
- ```
43
-
44
- **2. Generate a stats file from your bundler (e.g., webpack):**
45
-
46
- > ⚠️ **Important:**
47
- > You must generate a valid JSON stats file before running Packlyze.
48
- > For webpack, use the following command in your project folder:
49
-
50
- ```bash
51
- npx webpack --profile --json stats.json
52
- ```
53
- - This will create a readable `stats.json` file in your project directory.
54
-
55
- **3. Run Packlyze analysis (CLI):**
56
- ```bash
57
- packlyze analyze stats.json
58
- # or (if using npx)
59
- npx packlyze analyze stats.json
60
- ```
61
-
62
- **4. (Optional) Output an HTML report:**
63
- ```bash
64
- packlyze analyze stats.json -o ./reports/bundle-report.html
65
- ```
66
-
67
- ---
68
-
69
- ## 🐛 Common Issues & Solutions
70
-
71
- - **"Stats file not found":**
72
- Make sure `stats.json` exists in your folder.
73
- Generate it using your bundler (see above).
74
-
75
- - **"Invalid JSON in stats file":**
76
- Your stats file may be corrupted or not plain JSON.
77
- - Delete the file and re-run the correct webpack command.
78
- - Open `stats.json` in a text editor; it should start with `{` and be readable.
79
-
80
- - **"webpack not recognized":**
81
- Install webpack locally in your project:
82
- ```bash
83
- npm install --save-dev webpack webpack-cli
84
- ```
85
- Then use `npx webpack ...` to generate stats.
86
-
87
- - **"Module not found: Can't resolve './src'":**
88
- This means your webpack entry point is pointing to a directory instead of a file.
89
- **Fix:** Update your `webpack.config.js` entry point to point to an actual file:
90
-
91
- **How to find your entry point:**
92
- 1. Check your `package.json` for the `main` field
93
- 2. Look in your `src` folder for common entry files:
94
- - React: `App.tsx`, `App.jsx`, `app.tsx`, `app.jsx`, `index.tsx`, `index.jsx`
95
- - Vue: `main.js`, `main.ts`, `app.js`, `app.ts`
96
- - Angular: `main.ts`, `main.js`
97
- - Generic: `index.js`, `index.ts`, `main.js`, `main.ts`
98
- 3. Check your `webpack.config.js` or `vite.config.js` for the entry configuration
99
-
100
- **Example fixes:**
101
- ```javascript
102
- // webpack.config.js
103
- module.exports = {
104
- entry: './src/App.tsx', // React project
105
- // OR
106
- entry: './src/index.jsx', // ✅ React project
107
- // OR
108
- entry: './src/main.js', // Vue/Generic
109
- // NOT: entry: './src' // Directory won't work
110
- };
111
- ```
112
-
113
- **Quick check:** List files in your `src` folder:
114
- ```bash
115
- # Windows
116
- dir src
117
-
118
- # Mac/Linux
119
- ls src
120
- ```
121
-
122
- ---
123
-
124
- ## 📁 File Structure
125
-
126
- Typical structure for a Packlyze:
127
-
128
- ```
129
- Packlyze/
130
- ├── src/
131
- │ ├── types.ts # TypeScript interfaces
132
- │ ├── index.ts # Main entry point
133
- │ ├── cli.ts # CLI interface
134
- │ ├── analyzer/
135
- │ │ └── packlyze.ts # Core analysis logic
136
- │ └── visualization/
137
- │ └── reports.ts # HTML report generation
138
- ├── tests/
139
- └── analyzer.test.ts
140
- ├── dist/ # Compiled output
141
- ├── package.json
142
- ├── tsconfig.json
143
- ├── .eslintrc.json
144
- ├── .prettierrc
145
- ├── .gitignore
146
- └── README.md
147
- ```
148
-
149
-
150
- ## 📊 Analysis Output
151
-
152
- Packlyze provides detailed metrics, recommendations, and insights to help you optimize your bundle.
153
-
154
- The analyzer provides:
155
-
156
- ### Metrics
157
- - Total bundle size
158
- - Gzip size
159
- - Number of modules and chunks
160
- - Largest module
161
- - Average module size
162
-
163
- ### Recommendations
164
- - Critical: Address immediately
165
- - Warning: Consider optimizing
166
- - Info: Monitor for growth
167
-
168
- ### Insights
169
- - Tree-shaking issues.
170
- - Duplicate modules.
171
- - Large modules (configurable threshold, default >5% of bundle).
172
- - Module count and chunk analysis.
173
-
174
- ### HTML Report
175
-
176
- The generated HTML report is a single, static file with a modern dark UI:
177
-
178
- - **Header**: Run timestamp, optional baseline timestamp, and quick badges that summarize what you’re seeing.
179
- - **Metrics Grid**: Cards for total size, gzip size, modules, chunks, average module size, and largest module.
180
- - When a `--baseline` is provided, each metric shows a colored delta (green for improvement, red for regression).
181
- - **Recommendations**: Color-coded cards grouped by severity (critical, warning, info) with clear “Action” text.
182
- - **Top Modules Table**: Top 10 modules by size, with size and share of the bundle.
183
- - **Duplicate Modules Section**: Table with count, total size, potential savings, and example module names.
184
- - **Tree-Shaking Section**: List of CommonJS / `require`-style modules that may block tree-shaking.
185
-
186
- You can open the HTML report directly in any modern browser; no network access or JS bundling is required.
187
-
188
- ---
189
-
190
- ## ⚙️ CLI Usage & Options
191
-
192
- The main CLI entry point is the `analyze` command:
193
-
194
- ```bash
195
- packlyze analyze <statsFile> [options]
196
- ```
197
-
198
- ### Core options
199
-
200
- - `-o, --output <path>`: Path to the HTML report (default: `./bundle-report.html`).
201
- - `-j, --json`: Output raw JSON analysis to stdout instead of human-readable text/HTML.
202
- - `-v, --verbose`: Reserved for future verbose logging.
203
-
204
- ### Focus & filter options
205
-
206
- - `--only-duplicates`: Only print duplicate modules table in the CLI output.
207
- - `--only-large-modules`: Only print large modules table in the CLI output.
208
- - `--large-module-threshold <percent>`: Percentage of bundle size at which a module is considered “large” (default: `5`).
209
- - `--no-html`: Skip HTML report generation (useful in fast CLI-only workflows).
210
-
211
- ### Baseline comparison
212
-
213
- - `--baseline <statsFile>`: Provide a previous stats file to compare against.
214
-
215
- When a baseline is provided:
216
-
217
- - CLI summary prints deltas for total size, gzip size, module count, and chunk count.
218
- - HTML metrics cards show deltas under each metric (green good, red regression).
219
-
220
- Example:
221
-
222
- ```bash
223
- packlyze analyze dist/stats.new.json --baseline dist/stats.old.json
224
- ```
225
-
226
- ### CI-friendly thresholds
227
-
228
- Packlyze can enforce bundle-size budgets and fail your CI when limits are exceeded:
229
-
230
- - `--max-gzip-size <mb>`: Fail if gzip size exceeds this many megabytes.
231
- - `--max-initial-size <mb>`: Fail if initial bundle size (initial chunks) exceeds this many megabytes.
232
-
233
- When thresholds are violated:
234
-
235
- - The CLI prints a clear error message.
236
- - `packlyze` exits with a non-zero exit code so your CI job can fail on regressions.
237
-
238
- Example:
239
-
240
- ```bash
241
- packlyze analyze dist/stats.json \
242
- --max-gzip-size 1.2 \
243
- --max-initial-size 0.9 \
244
- --no-html
245
- ```
246
-
247
- ### Historical tracking
248
-
249
- Track bundle size over time:
250
-
251
- ```bash
252
- # Automatically saves to .packlyze/history.json after each analysis
253
- packlyze analyze stats.json
254
-
255
- # View trends
256
- packlyze trends
257
-
258
- # View more entries
259
- packlyze trends --limit 20
260
- ```
261
-
262
- ### Dependency graph
263
-
264
- Generate a dependency graph visualization:
265
-
266
- ```bash
267
- packlyze analyze stats.json --dependency-graph graph.dot
268
-
269
- # Render with Graphviz
270
- dot -Tsvg graph.dot -o graph.svg
271
- ```
272
-
273
- ## 🎯 Use Cases
274
-
275
- Common scenarios where Packlyze is helpful:
276
-
277
- - **Performance Optimization**: Identify and reduce bundle bloat
278
- - **Code Splitting**: Find optimal splitting points
279
- - **Dependency Analysis**: Detect unused or duplicate packages
280
- - **Tree-Shaking Audit**: Ensure modules support ES6 imports
281
- - **CI/CD Integration**: Monitor bundle size over time
282
-
283
- ## 📝 Examples
284
-
285
- Here are some example commands and configurations for different frameworks:
286
-
287
- ### Webpack Project
288
-
289
- ```javascript
290
- // webpack.config.js
291
- const path = require('path');
292
-
293
- module.exports = {
294
- // Entry point must be a FILE, not a directory
295
- // Common entry points:
296
- entry: './src/App.tsx', // React: App.tsx, App.jsx, app.tsx, app.jsx
297
- // OR: entry: './src/index.jsx', // React: index.tsx, index.jsx
298
- // OR: entry: './src/main.js', // Vue/Generic: main.js, main.ts
299
- // NOT: entry: './src' // ❌ Directory won't work
300
-
301
- output: {
302
- path: path.resolve(__dirname, 'dist'),
303
- filename: 'bundle.js'
304
- },
305
- module: {
306
- rules: [
307
- {
308
- test: /\.(js|jsx|ts|tsx)$/,
309
- exclude: /node_modules/,
310
- use: 'babel-loader'
311
- }
312
- ]
313
- },
314
- resolve: {
315
- extensions: ['.js', '.jsx', '.ts', '.tsx']
316
- }
317
- // ... your other config
318
- };
319
-
320
- // Generate stats.json
321
- // npx webpack --profile --json stats.json
322
-
323
- // Analyze with Packlyze
324
- // npx packlyze analyze stats.json
325
- ```
326
-
327
- ### Next.js Project
328
-
329
- ```bash
330
- # Build and analyze
331
- ANALYZE=true npm run build
332
- ```
333
-
334
- ### Vue/Nuxt Project
335
-
336
- ```bash
337
- # Generate stats
338
- npm run build -- --report
339
-
340
- # Analyze
341
- packlyze analyze dist/stats.json
342
- ```
343
-
344
- ## 🐛 Troubleshooting
345
-
346
- If you encounter issues, check the following:
347
-
348
- ### "Stats file not found"
349
- Ensure your stats.json path is correct and the file exists.
350
-
351
- ### "Invalid JSON"
352
- Verify your stats file is valid JSON. Generate it using your bundler's profiling mode.
353
-
354
- ### Large bundle warnings
355
- Consider:
356
- - Code splitting with dynamic imports
357
- - Tree-shaking verification
358
- - Removing unused dependencies
359
- - Using lighter alternatives
360
-
361
- ## 🤝 Contributing
362
-
363
- We welcome contributions! Please follow the steps below:
364
-
365
- Contributions welcome! Please:
366
-
367
- 1. Fork the repository
368
- 2. Create a feature branch
369
- 3. Make your changes
370
- 4. Add tests
371
- 5. Submit a pull request
372
-
373
- ## 📞 Support
374
-
375
- For issues and questions:
376
- - GitHub Issues: [https://github.com/iamabhshk/Packlyze/issues](https://github.com/iamabhshk/Packlyze/issues)
377
- - Email: [abhisheksrinivasan5@gmail.com]
378
-
379
- ## 🙏 Acknowledgments
380
-
381
- Packlyze is built with TypeScript, Commander.js, and Chalk. Special thanks to all contributors and users!
382
-
383
- Built with TypeScript, Commander.js, and Chalk
384
-
385
- ---
386
-
1
+ # Packlyze
2
+
3
+ [![NPM Version](https://img.shields.io/npm/v/packlyze.svg)](https://www.npmjs.com/package/packlyze)
4
+ [![Build Status](https://img.shields.io/github/workflow/status/iamabhshk/Packlyze/CI)](https://github.com/iamabhshk/Packlyze/actions)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+
7
+ ## Packlyze
8
+
9
+ Advanced bundle analyzer with insights, recommendations, historical tracking, and a sleek HTML report.
10
+
11
+ ## 📊 Features
12
+
13
+ - **Package Analysis**: Parse and analyze webpack, rollup, and esbuild stats files.
14
+ - **Auto-Detection & Setup Help**: Automatically detects missing webpack configs, entry points, and project types. Provides ready-to-use config templates.
15
+ - **Package-Level Insights**: Group modules by npm package to identify heavy dependencies.
16
+ - **Smart Recommendations**: Suggestions to optimize bundle size and structure.
17
+ - **Tree-Shaking Detection**: Identify modules and patterns that block tree-shaking.
18
+ - **Duplicate Detection**: Find and quantify duplicate modules with potential savings.
19
+ - **Chunk Analysis**: Analyze code-splitting efficiency and get optimization recommendations.
20
+ - **Unused Code Detection**: Identify potentially unused modules in your bundle.
21
+ - **Historical Tracking**: Track bundle size trends over time with `packlyze trends`.
22
+ - **Dependency Graph**: Generate Graphviz DOT files to visualize module dependencies.
23
+ - **Beautiful HTML Report**: Sleek, dark-themed, interactive report with search, filter, and sort.
24
+ - **Baseline Comparison**: Compare current vs previous stats to see regressions and improvements.
25
+ - **Multiple Export Formats**: Export to HTML, CSV, or Markdown.
26
+ - **Config File Support**: Use `.packlyzerc` or `packlyze.config.json` for project defaults.
27
+ - **CLI Tool**: Easy-to-use command-line interface with filters and CI-friendly thresholds.
28
+ - **Brotli Estimates**: Get Brotli compression size estimates (17% smaller than gzip).
29
+ - **TypeScript Ready**: Full TypeScript support with type definitions.
30
+
31
+ ## 🚀 Quick Start
32
+
33
+ Packlyze can be used in two main ways: as a CLI tool and as a Node.js/TypeScript library.
34
+
35
+ **1. Install Packlyze (globally or with npx):**
36
+
37
+ You can install Packlyze globally or use it via npx:
38
+
39
+ ```bash
40
+ npm install -g packlyze
41
+ # or
42
+ npx packlyze --help
43
+ ```
44
+
45
+ **2. Generate a stats file from your bundler (e.g., webpack):**
46
+
47
+ > ⚠️ **Important:**
48
+ > You must generate a valid JSON stats file before running Packlyze.
49
+ > For webpack, use the following command in your project folder:
50
+
51
+ ```bash
52
+ npx webpack --profile --json stats.json
53
+ ```
54
+ - This will create a readable `stats.json` file in your project directory.
55
+
56
+ **3. Run Packlyze analysis (CLI):**
57
+ ```bash
58
+ packlyze analyze stats.json
59
+ # or (if using npx)
60
+ npx packlyze analyze stats.json
61
+ ```
62
+
63
+ **4. (Optional) Output an HTML report:**
64
+ ```bash
65
+ packlyze analyze stats.json -o ./reports/bundle-report.html
66
+ ```
67
+
68
+ ---
69
+
70
+ ## 🐛 Common Issues & Solutions
71
+
72
+ - **"Stats file not found":**
73
+ Make sure `stats.json` exists in your folder.
74
+ Generate it using your bundler (see above).
75
+
76
+ - **"Invalid JSON in stats file":**
77
+ Your stats file may be corrupted or not plain JSON.
78
+ - Delete the file and re-run the correct webpack command.
79
+ - Open `stats.json` in a text editor; it should start with `{` and be readable.
80
+
81
+ - **"webpack not recognized":**
82
+ Install webpack locally in your project:
83
+ ```bash
84
+ npm install --save-dev webpack webpack-cli
85
+ ```
86
+ Then use `npx webpack ...` to generate stats.
87
+
88
+ - **"Module not found: Can't resolve './src'":**
89
+ This means your webpack entry point is pointing to a directory instead of a file.
90
+ **Packlyze will automatically detect this issue and help you fix it!**
91
+
92
+ **If you don't have a `webpack.config.js` file:**
93
+ Packlyze will:
94
+ - Auto-detect your entry point (e.g., `./src/App.tsx`, `./src/main.tsx`)
95
+ - Detect your project type (React, Vue, TypeScript, ES Modules, etc.)
96
+ - Provide a complete, ready-to-use webpack config template
97
+ - Tell you which file name to use (`.js` vs `.cjs` for ES module projects)
98
+ - List the required npm packages to install
99
+
100
+ Simply copy the provided config template, install the suggested packages, and regenerate your stats file.
101
+
102
+ **If you already have a `webpack.config.js` file:**
103
+ Packlyze will:
104
+ - Auto-detect the correct entry point
105
+ - Show you exactly what to change in your config
106
+
107
+ **How Packlyze detects entry points:**
108
+ Packlyze scans your `src` folder for common entry files in this priority order:
109
+ - React: `App.tsx`, `App.jsx`, `index.tsx`, `index.jsx`
110
+ - Generic: `main.ts`, `main.js`, `main.tsx`, `main.jsx`, `index.ts`, `index.js`
111
+ - Vue/Angular: `app.ts`, `app.js`
112
+
113
+ **Example fixes:**
114
+ ```javascript
115
+ // webpack.config.js (or webpack.config.cjs for ES module projects)
116
+ module.exports = {
117
+ entry: './src/App.tsx', // ✅ React project
118
+ // OR
119
+ entry: './src/index.jsx', // ✅ React project
120
+ // OR
121
+ entry: './src/main.js', // ✅ Vue/Generic
122
+ // NOT: entry: './src' // ❌ Directory won't work
123
+ };
124
+ ```
125
+
126
+ **Note for ES Module projects:**
127
+ If your `package.json` has `"type": "module"`, you need to use `webpack.config.cjs` instead of `webpack.config.js`. Packlyze will automatically detect this and suggest the correct filename.
128
+
129
+ ---
130
+
131
+ ## 📁 File Structure
132
+
133
+ Typical structure for a Packlyze:
134
+
135
+ ```
136
+ Packlyze/
137
+ ├── src/
138
+ ├── types.ts # TypeScript interfaces
139
+ ├── index.ts # Main entry point
140
+ ├── cli.ts # CLI interface
141
+ ├── analyzer/
142
+ │ │ └── packlyze.ts # Core analysis logic
143
+ │ └── visualization/
144
+ │ └── reports.ts # HTML report generation
145
+ ├── tests/
146
+ └── analyzer.test.ts
147
+ ├── dist/ # Compiled output
148
+ ├── package.json
149
+ ├── tsconfig.json
150
+ ├── .eslintrc.json
151
+ ├── .prettierrc
152
+ ├── .gitignore
153
+ └── README.md
154
+ ```
155
+
156
+
157
+ ## 📊 Analysis Output
158
+
159
+ Packlyze provides detailed metrics, recommendations, and insights to help you optimize your bundle.
160
+
161
+ The analyzer provides:
162
+
163
+ ### Metrics
164
+ - Total bundle size
165
+ - Gzip size
166
+ - Number of modules and chunks
167
+ - Largest module
168
+ - Average module size
169
+
170
+ ### Recommendations
171
+ - Critical: Address immediately
172
+ - Warning: Consider optimizing
173
+ - Info: Monitor for growth
174
+
175
+ ### Insights
176
+ - Tree-shaking issues.
177
+ - Duplicate modules.
178
+ - Large modules (configurable threshold, default >5% of bundle).
179
+ - Module count and chunk analysis.
180
+
181
+ ### HTML Report
182
+
183
+ The generated HTML report is a single, static file with a modern dark UI:
184
+
185
+ - **Header**: Run timestamp, optional baseline timestamp, and quick badges that summarize what you’re seeing.
186
+ - **Metrics Grid**: Cards for total size, gzip size, modules, chunks, average module size, and largest module.
187
+ - When a `--baseline` is provided, each metric shows a colored delta (green for improvement, red for regression).
188
+ - **Recommendations**: Color-coded cards grouped by severity (critical, warning, info) with clear “Action” text.
189
+ - **Top Modules Table**: Top 10 modules by size, with size and share of the bundle.
190
+ - **Duplicate Modules Section**: Table with count, total size, potential savings, and example module names.
191
+ - **Tree-Shaking Section**: List of CommonJS / `require`-style modules that may block tree-shaking.
192
+
193
+ You can open the HTML report directly in any modern browser; no network access or JS bundling is required.
194
+
195
+ ---
196
+
197
+ ## ⚙️ CLI Usage & Options
198
+
199
+ The main CLI entry point is the `analyze` command:
200
+
201
+ ```bash
202
+ packlyze analyze <statsFile> [options]
203
+ ```
204
+
205
+ ### Core options
206
+
207
+ - `-o, --output <path>`: Path to the HTML report (default: `./bundle-report.html`).
208
+ - `-j, --json`: Output raw JSON analysis to stdout instead of human-readable text/HTML.
209
+ - `-v, --verbose`: Reserved for future verbose logging.
210
+
211
+ ### Focus & filter options
212
+
213
+ - `--only-duplicates`: Only print duplicate modules table in the CLI output.
214
+ - `--only-large-modules`: Only print large modules table in the CLI output.
215
+ - `--large-module-threshold <percent>`: Percentage of bundle size at which a module is considered “large” (default: `5`).
216
+ - `--no-html`: Skip HTML report generation (useful in fast CLI-only workflows).
217
+
218
+ ### Baseline comparison
219
+
220
+ - `--baseline <statsFile>`: Provide a previous stats file to compare against.
221
+
222
+ When a baseline is provided:
223
+
224
+ - CLI summary prints deltas for total size, gzip size, module count, and chunk count.
225
+ - HTML metrics cards show deltas under each metric (green good, red regression).
226
+
227
+ Example:
228
+
229
+ ```bash
230
+ packlyze analyze dist/stats.new.json --baseline dist/stats.old.json
231
+ ```
232
+
233
+ ### CI-friendly thresholds
234
+
235
+ Packlyze can enforce bundle-size budgets and fail your CI when limits are exceeded:
236
+
237
+ - `--max-gzip-size <mb>`: Fail if gzip size exceeds this many megabytes.
238
+ - `--max-initial-size <mb>`: Fail if initial bundle size (initial chunks) exceeds this many megabytes.
239
+
240
+ When thresholds are violated:
241
+
242
+ - The CLI prints a clear error message.
243
+ - `packlyze` exits with a non-zero exit code so your CI job can fail on regressions.
244
+
245
+ Example:
246
+
247
+ ```bash
248
+ packlyze analyze dist/stats.json \
249
+ --max-gzip-size 1.2 \
250
+ --max-initial-size 0.9 \
251
+ --no-html
252
+ ```
253
+
254
+ ### Historical tracking
255
+
256
+ Track bundle size over time:
257
+
258
+ ```bash
259
+ # Automatically saves to .packlyze/history.json after each analysis
260
+ packlyze analyze stats.json
261
+
262
+ # View trends
263
+ packlyze trends
264
+
265
+ # View more entries
266
+ packlyze trends --limit 20
267
+ ```
268
+
269
+ ### Dependency graph
270
+
271
+ Generate a dependency graph visualization:
272
+
273
+ ```bash
274
+ packlyze analyze stats.json --dependency-graph graph.dot
275
+
276
+ # Render with Graphviz
277
+ dot -Tsvg graph.dot -o graph.svg
278
+ ```
279
+
280
+ ## 🎯 Use Cases
281
+
282
+ Common scenarios where Packlyze is helpful:
283
+
284
+ - **Performance Optimization**: Identify and reduce bundle bloat
285
+ - **Code Splitting**: Find optimal splitting points
286
+ - **Dependency Analysis**: Detect unused or duplicate packages
287
+ - **Tree-Shaking Audit**: Ensure modules support ES6 imports
288
+ - **CI/CD Integration**: Monitor bundle size over time
289
+
290
+ ## 📝 Examples
291
+
292
+ Here are some example commands and configurations for different frameworks:
293
+
294
+ ### Webpack Project
295
+
296
+ ```javascript
297
+ // webpack.config.js
298
+ const path = require('path');
299
+
300
+ module.exports = {
301
+ // Entry point must be a FILE, not a directory
302
+ // Common entry points:
303
+ entry: './src/App.tsx', // React: App.tsx, App.jsx, app.tsx, app.jsx
304
+ // OR: entry: './src/index.jsx', // React: index.tsx, index.jsx
305
+ // OR: entry: './src/main.js', // Vue/Generic: main.js, main.ts
306
+ // NOT: entry: './src' // ❌ Directory won't work
307
+
308
+ output: {
309
+ path: path.resolve(__dirname, 'dist'),
310
+ filename: 'bundle.js'
311
+ },
312
+ module: {
313
+ rules: [
314
+ {
315
+ test: /\.(js|jsx|ts|tsx)$/,
316
+ exclude: /node_modules/,
317
+ use: 'babel-loader'
318
+ }
319
+ ]
320
+ },
321
+ resolve: {
322
+ extensions: ['.js', '.jsx', '.ts', '.tsx']
323
+ }
324
+ // ... your other config
325
+ };
326
+
327
+ // Generate stats.json
328
+ // npx webpack --profile --json stats.json
329
+
330
+ // Analyze with Packlyze
331
+ // npx packlyze analyze stats.json
332
+ ```
333
+
334
+ ### Next.js Project
335
+
336
+ ```bash
337
+ # Build and analyze
338
+ ANALYZE=true npm run build
339
+ ```
340
+
341
+ ### Vue/Nuxt Project
342
+
343
+ ```bash
344
+ # Generate stats
345
+ npm run build -- --report
346
+
347
+ # Analyze
348
+ packlyze analyze dist/stats.json
349
+ ```
350
+
351
+ ## 🐛 Troubleshooting
352
+
353
+ If you encounter issues, check the following:
354
+
355
+ ### "Stats file not found"
356
+ Ensure your stats.json path is correct and the file exists.
357
+
358
+ ### "Invalid JSON"
359
+ Verify your stats file is valid JSON. Generate it using your bundler's profiling mode.
360
+
361
+ ### Large bundle warnings
362
+ Consider:
363
+ - Code splitting with dynamic imports
364
+ - Tree-shaking verification
365
+ - Removing unused dependencies
366
+ - Using lighter alternatives
367
+
368
+ ## 🤝 Contributing
369
+
370
+ We welcome contributions! Please follow the steps below:
371
+
372
+ Contributions welcome! Please:
373
+
374
+ 1. Fork the repository
375
+ 2. Create a feature branch
376
+ 3. Make your changes
377
+ 4. Add tests
378
+ 5. Submit a pull request
379
+
380
+ ## 📞 Support
381
+
382
+ For issues and questions:
383
+ - GitHub Issues: [https://github.com/iamabhshk/Packlyze/issues](https://github.com/iamabhshk/Packlyze/issues)
384
+ - Email: [abhisheksrinivasan5@gmail.com]
385
+
386
+ ## 🙏 Acknowledgments
387
+
388
+ Packlyze is built with TypeScript, Commander.js, and Chalk. Special thanks to all contributors and users!
389
+
390
+ Built with TypeScript, Commander.js, and Chalk
391
+
392
+ ---
393
+
387
394
  **Made with ❤️ by Abhishek**