Skip to content

Commit 6fe465a

Browse files
shiftEscapeshiftEscape
committed
chore: docs and build updates
1 parent 9886133 commit 6fe465a

3 files changed

Lines changed: 130 additions & 52 deletions

File tree

‎README.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# 📦 astro-bundle-budget-workspace
2+
3+
Monorepo for [`astro-bundle-budget`](https://www.npmjs.com/package/astro-bundle-budget) — a build-time JS/CSS bundle size budget integration for Astro.
4+
5+
## 📁 Structure
6+
7+
```
8+
astro-bundle-budget/
9+
├── packages/
10+
│ └── astro-bundle-budget/ # the published npm package
11+
└── demo/ # local Astro site for testing the integration
12+
```
13+
14+
## 🚀 Getting started
15+
16+
Install all workspace dependencies from the root:
17+
18+
```bash
19+
npm install
20+
```
21+
22+
## ⚙️ Development workflow
23+
24+
**1️⃣ Build the package** (required before testing in the demo):
25+
26+
```bash
27+
npm run build:pkg
28+
```
29+
30+
Or keep it watching for changes in a separate terminal:
31+
32+
```bash
33+
cd packages/astro-bundle-budget && npm run dev
34+
```
35+
36+
**2️⃣ Run the demo build** to see the integration in action:
37+
38+
```bash
39+
npm run build:demo
40+
```
41+
42+
**3️⃣ Run both in one shot:**
43+
44+
```bash
45+
npm run test:demo
46+
```
47+
48+
Add these scripts to the root `package.json`:
49+
50+
```json
51+
{
52+
"scripts": {
53+
"build:pkg": "npm run build --workspace=packages/astro-bundle-budget",
54+
"build:demo": "npm run build --workspace=demo",
55+
"test:demo": "npm run build:pkg && npm run build:demo"
56+
}
57+
}
58+
```
59+
60+
## 🧪 Running tests
61+
62+
```bash
63+
npm test --workspace=packages/astro-bundle-budget
64+
```
65+
66+
## 📦 Package
67+
68+
See [`packages/astro-bundle-budget/README.md`](./packages/astro-bundle-budget/README.md) for full usage docs, options, and examples.
69+
70+
## 📄 License
71+
72+
MIT © [Alvin James Bellero](https://github.com/shiftEscape)

‎package.json‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,11 @@
44
"workspaces": [
55
"demo",
66
"packages/*"
7-
]
7+
],
8+
"scripts": {
9+
"test:pkg": "npm test --workspace=packages/astro-bundle-budget",
10+
"build:pkg": "npm run build --workspace=packages/astro-bundle-budget",
11+
"build:demo": "npm run build --workspace=demo",
12+
"test:demo": "npm run build:pkg && npm run build:demo"
13+
}
814
}

‎packages/astro-bundle-budget/README.md‎

Lines changed: 51 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# astro-bundle-budget
1+
# 🚀 astro-bundle-budget
22

3-
Build-time JS/CSS bundle size budgets for Astro. Inspect every asset and page payload at the end of `astro build` — and optionally fail CI when you exceed your thresholds.
3+
Build-time JS/CSS bundle size budgets for Astro. Inspect every asset and page payload at the end of `astro build` — and optionally fail CI when you exceed your thresholds. 📊
44

55
```
66
▶ astro-bundle-budget Analysing bundle…
@@ -22,100 +22,100 @@ Build-time JS/CSS bundle size budgets for Astro. Inspect every asset and page pa
2222
1 budget violation exceeded.
2323
```
2424

25-
## Install
25+
## 📦 Install
2626

2727
```bash
2828
npm install -D astro-bundle-budget
2929
# or
3030
pnpm add -D astro-bundle-budget
3131
```
3232

33-
## Usage
33+
## 🛠️ Usage
3434

3535
```js
3636
// astro.config.mjs
37-
import { defineConfig } from 'astro/config'
38-
import bundleBudget from 'astro-bundle-budget'
37+
import { defineConfig } from "astro/config";
38+
import bundleBudget from "astro-bundle-budget";
3939

4040
export default defineConfig({
4141
integrations: [
4242
bundleBudget({
4343
// Per-file limits — first matching glob wins
4444
budgets: [
45-
{ path: 'assets/vendor-*.js', budget: '50 kB' },
46-
{ path: '**/*.js', budget: '100 kB' },
47-
{ path: '**/*.css', budget: '20 kB' },
45+
{ path: "assets/vendor-*.js", budget: "50 kB" },
46+
{ path: "**/*.js", budget: "100 kB" },
47+
{ path: "**/*.css", budget: "20 kB" },
4848
],
4949

5050
// Per-page limits — total payload a single page may reference
5151
pageBudgets: [
52-
{ type: 'js', budget: '150 kB' },
53-
{ type: 'css', budget: '30 kB' },
54-
{ type: 'total', budget: '200 kB', compression: 'gzip' },
52+
{ type: "js", budget: "150 kB" },
53+
{ type: "css", budget: "30 kB" },
54+
{ type: "total", budget: "200 kB", compression: "gzip" },
5555
],
5656
}),
5757
],
58-
})
58+
});
5959
```
6060

61-
### Zero-config (size display only)
61+
### ⚡ Zero-config (size display only)
6262

6363
Add the integration with no options to get a free asset table after every build:
6464

6565
```js
66-
integrations: [bundleBudget()]
66+
integrations: [bundleBudget()];
6767
```
6868

69-
## Options
69+
## ⚙️ Options
7070

71-
| Option | Type | Default | Description |
72-
|---|---|---|---|
73-
| `budgets` | `BudgetRule[]` | `[]` | Per-file glob rules |
74-
| `pageBudgets` | `PageBudget[]` | `[]` | Per-page total payload rules |
75-
| `failOnExceed` | `boolean` | `true` | Exit 1 when a budget is exceeded |
76-
| `report` | `boolean` | `false` | Write `bundle-budget-report.json` to `outDir` |
77-
| `reportPath` | `string` | `'bundle-budget-report.json'` | Report filename |
78-
| `verbose` | `boolean` | `false` | Show all assets + per-page breakdown |
71+
| Option | Type | Default | Description |
72+
| -------------- | -------------- | ----------------------------- | --------------------------------------------- |
73+
| `budgets` | `BudgetRule[]` | `[]` | Per-file glob rules |
74+
| `pageBudgets` | `PageBudget[]` | `[]` | Per-page total payload rules |
75+
| `failOnExceed` | `boolean` | `true` | Exit 1 when a budget is exceeded |
76+
| `report` | `boolean` | `false` | Write `bundle-budget-report.json` to `outDir` |
77+
| `reportPath` | `string` | `'bundle-budget-report.json'` | Report filename |
78+
| `verbose` | `boolean` | `false` | Show all assets + per-page breakdown |
7979

80-
### `BudgetRule`
80+
### 📋 `BudgetRule`
8181

8282
```ts
8383
interface BudgetRule {
84-
path: string // minimatch glob against asset path
85-
budget: number | string // bytes or '100 kB', '1.5 MB'
86-
compression?: 'none' | 'gzip' | 'brotli' // default: 'none'
84+
path: string; // minimatch glob against asset path
85+
budget: number | string; // bytes or '100 kB', '1.5 MB'
86+
compression?: "none" | "gzip" | "brotli"; // default: 'none'
8787
}
8888
```
8989

90-
### `PageBudget`
90+
### 📄 `PageBudget`
9191

9292
```ts
9393
interface PageBudget {
94-
type: 'js' | 'css' | 'total' // what to measure per page
95-
budget: number | string
96-
compression?: 'none' | 'gzip' | 'brotli'
94+
type: "js" | "css" | "total"; // what to measure per page
95+
budget: number | string;
96+
compression?: "none" | "gzip" | "brotli";
9797
}
9898
```
9999

100-
### Size strings
100+
### 📐 Size strings
101101

102102
Accepted formats: `'100 kB'`, `'1.5 MB'`, `'50 KB'`, `'200kb'`, `'1.2 MiB'`, or a plain number (bytes).
103103

104-
### Compression
104+
### 🗜️ Compression
105105

106106
Set `compression: 'gzip'` or `compression: 'brotli'` to measure the wire size your users actually receive. Useful for `pageBudgets` targeting real-world performance.
107107

108-
## CI integration
108+
## 🔄 CI integration
109109

110110
Because `failOnExceed: true` by default, `astro build` exits with code 1 when any budget is exceeded — no extra setup needed for GitHub Actions, GitLab CI, or any other CI platform.
111111

112112
To turn violations into warnings (still shows the table, never fails):
113113

114114
```js
115-
bundleBudget({ failOnExceed: false })
115+
bundleBudget({ failOnExceed: false });
116116
```
117117

118-
## JSON report
118+
## 📋 JSON report
119119

120120
Enable `report: true` to write a machine-readable report to `dist/bundle-budget-report.json`:
121121

@@ -134,25 +134,25 @@ Enable `report: true` to write a machine-readable report to `dist/bundle-budget-
134134

135135
Store this file as a CI artefact and diff it between builds to track bundle growth over time.
136136

137-
## vs. alternatives
137+
## ⚖️ vs. alternatives
138138

139-
| | astro-bundle-budget | vite-plugin-bundlesize | rollup-plugin-visualizer |
140-
|---|---|---|---|
141-
| Astro-native config | ✓ | ✗ (Vite config) | ✗ |
142-
| Per-page breakdown | ✓ | ✗ | ✗ |
143-
| Fails the build | ✓ | ✓ | ✗ |
144-
| Compression budgets | ✓ | ✓ | ✗ |
145-
| Static HTML report | JSON | `bundlemeta.json` | `stats.html` |
146-
| Zero extra deps | ✓ | ✗ | ✗ |
139+
| | astro-bundle-budget | vite-plugin-bundlesize | rollup-plugin-visualizer |
140+
| ------------------- | ------------------- | ---------------------- | ------------------------ |
141+
| Astro-native config | ✓ | ✗ (Vite config) | ✗ |
142+
| Per-page breakdown | ✓ | ✗ | ✗ |
143+
| Fails the build | ✓ | ✓ | ✗ |
144+
| Compression budgets | ✓ | ✓ | ✗ |
145+
| Static HTML report | JSON | `bundlemeta.json` | `stats.html` |
146+
| Zero extra deps | ✓ | ✗ | ✗ |
147147

148-
## License
148+
## 📄 License
149149

150150
MIT
151151

152-
## Contributing
152+
## 🤝 Contributing
153153

154-
Issues and PRs welcome. For questions, find us in the [`#integrations` channel on the Astro Discord](https://astro.build/chat).
154+
Issues and PRs welcome. For questions, find us in the [`#integrations` channel on the Astro Discord](https://astro.build/chat). 💬
155155

156-
## Acknowledgements
156+
## 🙏 Acknowledgements
157157

158-
Built with the [Astro Integration API](https://docs.astro.build/en/reference/integrations-reference/) and listed in the [Astro Integrations Library](https://astro.build/integrations/).
158+
Built with the [Astro Integration API](https://docs.astro.build/en/reference/integrations-reference/) and listed in the [Astro Integrations Library](https://astro.build/integrations/). 🌟

0 commit comments

Comments
 (0)