Skip to content

Commit 17e993b

Browse files
irenteria0617irenteria0617
committed
Release v0.2.0 - Browser support
Major new feature: Full browser compatibility with 100% API parity Added: - Complete platform abstraction layer for Node.js and Browser - Browser implementations for FileSystem and ImageProcessor - Pure JavaScript MD5 for browser encryption - esbuild-based browser bundle (~600KB minified) - 80+ browser examples in examples/browser/ - BROWSER.md and BROWSER_MIGRATION.md documentation Breaking Changes: - Methods involving I/O are now async (save, toBuffer, registerFont, image) Fixes: - Table text alignment with proper baseline calculations - Font parameter support in text() method - File attachments handling for undefined values - Encryption support in browsers Dependencies: - Added: buffer, esbuild - Changed: sharp moved to optionalDependencies
1 parent cff1cff commit 17e993b

28 files changed

Lines changed: 4944 additions & 113 deletions

‎BROWSER.md‎

Lines changed: 405 additions & 0 deletions
Large diffs are not rendered by default.

‎BROWSER_MIGRATION.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
# Browser Migration Summary
2+
3+
## 🎉 What's New
4+
5+
PDFStudio v0.2.0 is now **isomorphic** - it works in both Node.js AND browsers!
6+
7+
## 🏗️ Architecture Changes
8+
9+
### Platform Abstraction Layer
10+
11+
Created a new platform abstraction layer to support multiple environments:
12+
13+
```
14+
src/
15+
├── platform/
16+
│ ├── interfaces/ # Abstract interfaces
17+
│ │ ├── IFileSystem.ts
18+
│ │ └── IImageProcessor.ts
19+
│ ├── node/ # Node.js implementations
20+
│ │ ├── NodeFileSystem.ts
21+
│ │ └── NodeImageProcessor.ts
22+
│ ├── browser/ # Browser implementations
23+
│ │ ├── BrowserFileSystem.ts
24+
│ │ └── BrowserImageProcessor.ts
25+
│ └── PlatformFactory.ts # Auto-detects environment
26+
```
27+
28+
### Key Changes
29+
30+
#### 1. Image Processing
31+
- **Node.js**: Still uses `sharp` for optimal performance
32+
- **Browser**: Uses Canvas API for image processing
33+
- **Interface**: `IImageProcessor` provides unified API
34+
35+
#### 2. File System
36+
- **Node.js**: Uses native `fs` module
37+
- **Browser**: Uses FileReader API, fetch API, and Blob API
38+
- **Interface**: `IFileSystem` provides unified API
39+
40+
#### 3. Async APIs
41+
Several methods are now async to support browser file loading:
42+
43+
```typescript
44+
// Before (Node.js only)
45+
doc.registerFont({ name: 'MyFont', source: './font.ttf' });
46+
doc.save('output.pdf');
47+
48+
// After (Node.js + Browser)
49+
await doc.registerFont({ name: 'MyFont', source: './font.ttf' });
50+
await doc.save('output.pdf');
51+
```
52+
53+
### Breaking Changes
54+
55+
#### Async Methods
56+
57+
The following methods are now `async`:
58+
59+
- `PDFDocument.registerFont()` → `async registerFont()`
60+
- `PDFDocument.save()` → `async save()`
61+
- `PDFDocument.toBuffer()` → `async toBuffer()`
62+
- `PDFDocument.end()` → `async end()`
63+
- `PDFWriter.registerCustomFont()` → `async registerCustomFont()`
64+
- `PDFWriter.generate()` → `async generate()`
65+
- `PDFWriter.embedImage()` → `async embedImage()`
66+
- `ImageParser.load()` → `async load()`
67+
68+
#### Migration Example
69+
70+
**Before (v0.1.x):**
71+
```typescript
72+
const doc = new PDFDocument();
73+
doc.registerFont({ name: 'MyFont', source: './font.ttf' });
74+
doc.text('Hello', 100, 100);
75+
doc.save('output.pdf');
76+
```
77+
78+
**After (v0.2.x):**
79+
```typescript
80+
const doc = new PDFDocument();
81+
await doc.registerFont({ name: 'MyFont', source: './font.ttf' });
82+
doc.text('Hello', 100, 100);
83+
await doc.save('output.pdf');
84+
```
85+
86+
### Dependencies Changes
87+
88+
#### New Dependencies
89+
- `buffer` - Buffer polyfill for browsers
90+
- `esbuild` - Build tool for browser bundle
91+
92+
#### Modified Dependencies
93+
- `sharp` - Moved to `optionalDependencies` (not required in browsers)
94+
95+
### Build System
96+
97+
New build scripts:
98+
99+
```json
100+
{
101+
"scripts": {
102+
"build": "npm run build:node && npm run build:browser",
103+
"build:node": "tsc",
104+
"build:browser": "node scripts/build-browser.js"
105+
}
106+
}
107+
```
108+
109+
Output files:
110+
- `dist/index.js` - Node.js version (CommonJS)
111+
- `dist/pdfstudio.standalone.js` - Browser version (IIFE, minified)
112+
- `dist/pdfstudio.standalone.debug.js` - Browser version (IIFE, debug)
113+
114+
## 🚀 New Features
115+
116+
### Browser Support
117+
- ✅ Generate PDFs directly in the browser
118+
- ✅ No server required
119+
- ✅ Same API as Node.js
120+
- ✅ Modern browsers (Chrome, Firefox, Safari, Edge)
121+
122+
### File Handling
123+
- ✅ Load images from URLs
124+
- ✅ Load images from File objects (`<input type="file">`)
125+
- ✅ Load images from data URLs
126+
- ✅ Load fonts from URLs or File objects
127+
- ✅ Download PDFs or get as Blob
128+
129+
### Browser-Specific Features
130+
```javascript
131+
// Download PDF
132+
await doc.save('output.pdf'); // Triggers download
133+
134+
// Get as Blob (for upload, viewing, etc.)
135+
const buffer = await doc.toBuffer();
136+
const blob = new Blob([buffer], { type: 'application/pdf' });
137+
const url = URL.createObjectURL(blob);
138+
139+
// View in browser
140+
window.open(url, '_blank');
141+
142+
// Upload to server
143+
const formData = new FormData();
144+
formData.append('pdf', blob, 'document.pdf');
145+
await fetch('/api/upload', { method: 'POST', body: formData });
146+
```
147+
148+
## 📚 Documentation
149+
150+
New documentation:
151+
- `BROWSER.md` - Complete browser guide
152+
- `examples/browser/` - Browser examples
153+
- `examples/browser/README.md` - Browser examples documentation
154+
- Updated main README with browser section
155+
156+
## 🔄 Migration Checklist
157+
158+
For existing users upgrading from v0.1.x to v0.2.x:
159+
160+
- [ ] Update all `doc.save()` calls to `await doc.save()`
161+
- [ ] Update all `doc.registerFont()` calls to `await doc.registerFont()`
162+
- [ ] Update all `doc.toBuffer()` calls to `await doc.toBuffer()`
163+
- [ ] Update all `doc.end()` calls to `await doc.end()`
164+
- [ ] Update all `ImageParser.load()` calls to `await ImageParser.load()`
165+
- [ ] Wrap affected code in `async` functions
166+
- [ ] Test your application
167+
168+
### Example Migration
169+
170+
**Before:**
171+
```typescript
172+
function generateInvoice() {
173+
const doc = new PDFDocument();
174+
doc.registerFont({ name: 'Arial', source: './arial.ttf' });
175+
doc.text('Invoice', 100, 100);
176+
doc.save('invoice.pdf');
177+
}
178+
```
179+
180+
**After:**
181+
```typescript
182+
async function generateInvoice() {
183+
const doc = new PDFDocument();
184+
await doc.registerFont({ name: 'Arial', source: './arial.ttf' });
185+
doc.text('Invoice', 100, 100);
186+
await doc.save('invoice.pdf');
187+
}
188+
```
189+
190+
## 🎯 Benefits
191+
192+
1. **Universal**: Write once, run anywhere (Node.js + Browser)
193+
2. **No Breaking API**: Same API for both environments
194+
3. **Better Performance**: Optimized implementations for each platform
195+
4. **Modern**: Uses latest browser APIs (Canvas, Blob, Web Crypto)
196+
5. **Future-Proof**: Foundation for other platforms (React Native, Electron)
197+
198+
## 🐛 Known Limitations
199+
200+
### Browser Version
201+
1. **Memory**: Large PDFs (>50MB) may hit browser memory limits
202+
2. **Performance**: Image processing slightly slower than Node.js (Canvas vs sharp)
203+
3. **Sync Crypto**: Some crypto operations are async in browsers
204+
205+
## 📞 Support
206+
207+
- 📖 [Browser Documentation](BROWSER.md)
208+
- 📖 [Main Documentation](README.md)
209+
- 💬 [GitHub Issues](https://github.com/pdfstudio-dev/pdfstudio/issues)
210+
- 📧 Email: hello@ideas2code.dev

‎CHANGELOG.md‎

Lines changed: 98 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,104 @@ All notable changes to this project will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8-
## [1.0.0] - 2025-11-17
8+
## [0.2.0] - 2025-01-21
9+
10+
### 🎉 Major New Feature: Browser Support
11+
12+
PDFStudio now works natively in web browsers! Generate PDFs client-side with 100% API parity to the Node.js version.
13+
14+
### ✨ Added
15+
16+
#### 🌐 Browser Compatibility
17+
- **Complete Platform Abstraction** - Seamless Node.js/Browser compatibility via adapter pattern
18+
- **100% API Parity** - Identical API across Node.js and browsers
19+
- **All Features Supported** - Charts, tables, QR codes, encryption, forms, annotations, etc.
20+
- **Zero Server Dependencies** - Everything runs client-side
21+
- **Modern Browser Support** - Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
22+
- **Small Bundle Size** - ~600KB minified (including all features)
23+
- **TypeScript Support** - Full type definitions for browser environment
24+
25+
#### 🔐 Browser-Specific Implementations
26+
- **Pure JavaScript MD5** - Custom MD5 implementation for PDF encryption in browsers
27+
- **Web Crypto API Integration** - Secure random number generation
28+
- **Canvas-Based Image Processing** - No dependencies for image handling
29+
- **File System Abstraction** - `BrowserFileSystem` using Fetch API, FileReader, and Blob
30+
- **Image Processor Abstraction** - `BrowserImageProcessor` using Canvas/OffscreenCanvas
31+
- **Buffer Polyfill** - Full Buffer support via npm buffer package
32+
- **Automatic Download** - Trigger file downloads or get as Blob for uploading
33+
34+
#### 📦 Build System
35+
- **Dual Build Target** - Separate builds for Node.js (CommonJS) and Browser (IIFE)
36+
- **esbuild Integration** - Fast, optimized browser bundling
37+
- **Automatic Tree-Shaking** - Remove unused code
38+
- **Smart Polyfills** - Only include necessary polyfills (Buffer, crypto)
39+
- **Module Replacement** - Replace Node modules (fs, sharp) with browser equivalents
40+
- **Source Maps** - Debug support for both minified and debug builds
41+
42+
#### 📚 Documentation
43+
- **BROWSER.md** - Complete browser usage guide (406 lines)
44+
- **BROWSER_MIGRATION.md** - Migration guide for existing users (211 lines)
45+
- **80+ Browser Examples** - Interactive examples in `examples/browser/index.html`
46+
- **Updated README** - Expanded browser support section with examples
47+
48+
#### 🔧 API Improvements
49+
- **Async/Await Throughout** - All I/O operations now async
50+
- `registerFont()` → `async registerFont()`
51+
- `save()` → `async save()`
52+
- `toBuffer()` → `async toBuffer()`
53+
- `image()` → `async image()`
54+
- **Enhanced Text Method** - Added signature `text(text, x, y, fontSize, font)` for PDFKit compatibility
55+
- **Robust Error Handling** - `escapePDFString()` handles undefined values gracefully
56+
57+
### 🐛 Fixed
58+
- **Table Text Alignment** - Corrected vertical centering in table cells with proper baseline calculations
59+
- **File Attachments** - Fixed `escapePDFString()` crash when attachment name is undefined
60+
- **Font Selection** - Fixed font parameter being ignored in simple text() calls
61+
- **Crypto Compatibility** - MD5 hashing now works in browsers (previously unsupported)
62+
63+
### 🎨 Examples & Demos
64+
- **Invoice Generator** - Real-world invoice with tables and totals
65+
- **Business Report** - Multi-page report with KPIs and charts
66+
- **Certificate** - Professional certificate with vector graphics
67+
- **QR Code Examples** - Email, URL, WiFi, vCard, and more
68+
- **Form Examples** - Interactive forms with encryption
69+
- **Chart Gallery** - All 7 chart types with styling options
70+
71+
### 📐 Platform Differences
72+
| Feature | Node.js | Browser |
73+
|---------|---------|---------|
74+
| File I/O | `fs` module | `fetch()` / `FileReader` / `Blob` |
75+
| Image Processing | `sharp` (optional) | Canvas API |
76+
| Font Loading | File paths | URLs or File objects |
77+
| File Save | Disk write | Download trigger |
78+
| Buffer | Native | Polyfilled |
79+
| Crypto | Node crypto | Web Crypto + MD5 polyfill |
80+
81+
### 🔄 Breaking Changes
82+
- **Async Operations** - Methods involving I/O are now async (add `await`)
83+
- `doc.save()` → `await doc.save()`
84+
- `doc.toBuffer()` → `await doc.toBuffer()`
85+
- `doc.registerFont()` → `await doc.registerFont()`
86+
- `doc.image()` → `await doc.image()`
87+
88+
### 📦 Dependencies
89+
- **Added**: `buffer@^6.0.3` - Buffer polyfill for browsers
90+
- **Added**: `esbuild@^0.19.0` - Browser bundle builder
91+
- **Changed**: `sharp@^0.34.5` → `optionalDependencies` (not needed in browser)
92+
93+
### ⚡ Performance
94+
- **Optimized Bundle** - Tree-shaking reduces unused code
95+
- **Lazy Loading** - Platform adapters loaded on demand
96+
- **Efficient Polyfills** - Minimal overhead for browser environment
97+
98+
### 🧪 Testing
99+
- **All 180 Tests Pass** - Full compatibility maintained
100+
- **Cross-Platform Testing** - Verified on Node.js and browsers
101+
- **Browser Examples** - Comprehensive manual testing suite
102+
103+
---
104+
105+
## [0.1.1] - 2025-01-17
9106

10107
### 🎉 Initial Release
11108

0 commit comments

Comments
 (0)