Skip to content

Commit 7995e06

Browse files
sashamilenkovicsashamilenkovic
committed
docs: updates readme and scripts for refactor with frameworks
1 parent 0466dfb commit 7995e06

File tree

4 files changed

+226
-85
lines changed

4 files changed

+226
-85
lines changed

‎README.md‎

Lines changed: 159 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,120 +1,201 @@
11
# Nutrient Web SDK Examples
22

3-
This repository contains framework templates and feature examples for the [Nutrient Web SDK](https://www.nutrient.io/sdk/web).
3+
This repository contains framework integration examples for the [Nutrient Web SDK](https://www.nutrient.io/sdk/web).
44

55
- **Demo**: https://www.nutrient.io/demo/
66
- **Guides**: https://www.nutrient.io/guides/web/
77
- **API**: https://www.nutrient.io/guides/web/api/
88

9-
## 🏗️ Architecture
10-
11-
This repository is structured to separate framework scaffolding from Nutrient feature demonstrations:
9+
## 📁 Repository Structure
1210

1311
```
14-
├── frameworks/ # Framework templates (React, Vue, etc.)
15-
│ ├── react-js/ # React + JavaScript + Vite
16-
│ ├── react-ts/ # React + TypeScript + Vite
17-
│ ├── vue-js/ # Vue + JavaScript + Vite
18-
│ └── vue-ts/ # Vue + TypeScript + Vite
19-
└── examples/ # Framework-agnostic Nutrient features
20-
├── basic-viewer/ # Simple document loading
21-
└── magazine-mode/ # Advanced magazine-style viewer
12+
nutrient-web-examples/
13+
├── frameworks/ # Frontend framework examples with JS and TS variants
14+
│ ├── react/
15+
│ │ ├── JS/ # React + JavaScript + Vite
16+
│ │ └── TS/ # React + TypeScript + Vite
17+
│ ├── vue/
18+
│ │ ├── JS/ # Vue + JavaScript + Vite
19+
│ │ └── TS/ # Vue + TypeScript + Vite
20+
│ ├── svelte/
21+
│ │ ├── JS/ # Svelte + JavaScript + Vite
22+
│ │ └── TS/ # Svelte + TypeScript + Vite
23+
│ ├── solid/
24+
│ │ ├── js/ # SolidJS + JavaScript + Vite
25+
│ │ └── ts/ # SolidJS + TypeScript + Vite
26+
│ ├── angular/
27+
│ │ └── TS/ # Angular (TypeScript only)
28+
│ ├── next/
29+
│ │ ├── JS/ # Next.js + JavaScript
30+
│ │ └── TS/ # Next.js + TypeScript
31+
│ ├── nuxt/
32+
│ │ ├── JS/ # Nuxt + JavaScript
33+
│ │ └── TS/ # Nuxt + TypeScript
34+
│ ├── sveltekit/
35+
│ │ ├── js/ # SvelteKit + JavaScript
36+
│ │ └── ts/ # SvelteKit + TypeScript
37+
│ └── vanilla/
38+
│ ├── js/ # Vanilla JS + Vite
39+
│ └── ts/ # Vanilla TS + Vite
40+
└── examples/ # Specialized examples and legacy integrations
41+
├── webpack/ # Webpack-based example
42+
├── electron/ # Electron desktop app
43+
├── pwa/ # Progressive Web App
44+
├── laravel/ # Laravel PHP integration
45+
├── salesforce/ # Salesforce integration
46+
└── ... # Other specialized examples
2247
```
2348

24-
## 🚀 Framework Templates
25-
26-
Framework templates provide the minimal setup needed to integrate Nutrient Web SDK with popular frameworks. Each template includes:
27-
28-
- Modern build tooling (Vite)
29-
- Proper TypeScript configuration (for TS variants)
30-
- Basic Nutrient integration
31-
- Development server setup
32-
33-
### Available Templates
34-
35-
| Framework | Language | Template Directory |
36-
|-----------|----------|-------------------|
37-
| React | JavaScript | `frameworks/react-js/` |
38-
| React | TypeScript | `frameworks/react-ts/` |
39-
| Vue | JavaScript | `frameworks/vue-js/` |
40-
| Vue | TypeScript | `frameworks/vue-ts/` |
49+
## 🚀 Framework Examples
4150

42-
Each framework template follows the same pattern:
43-
```javascript
44-
// Framework handles lifecycle and container
45-
// Example handles Nutrient-specific logic
51+
Each framework example demonstrates Nutrient Web SDK integration with **4 feature examples**:
4652

47-
import { loadBasicViewer } from '../examples/basic-viewer/implementation.js';
53+
### Available Examples in Each Framework
4854

49-
// In your component
50-
const instance = await loadBasicViewer(containerElement);
51-
```
52-
53-
## 🎯 Examples
54-
55-
Examples demonstrate specific Nutrient Web SDK features and are framework-agnostic. Each example provides:
55+
| Example | Description | Key Features |
56+
| ------------------- | ------------------------- | ---------------------------------------------- |
57+
| **Basic Viewer** | Simple PDF viewing | Document loading, basic navigation |
58+
| **Magazine Mode** | Magazine-style reader | Double-page layout, custom toolbar, fullscreen |
59+
| **Custom Overlays** | Interactive page overlays | Click handlers, custom UI elements on pages |
60+
| **Watermarks** | Document watermarking | Adding text/image watermarks to PDFs |
5661

57-
- Pure JavaScript implementation
58-
- Comprehensive documentation
59-
- Framework integration guidance
62+
### Supported Frameworks
6063

61-
### Available Examples
62-
63-
| Example | Description | Features |
64-
|---------|-------------|----------|
65-
| `basic-viewer/` | Simple PDF viewing | Document loading, basic controls |
66-
| `magazine-mode/` | Magazine-style reader | Double-page layout, custom toolbar, fullscreen |
64+
| Framework | JavaScript | TypeScript | Build Tool | Meta-Framework |
65+
| --------- | ---------- | ---------- | ----------- | -------------- |
66+
| React | ✅ | ✅ | Vite | - |
67+
| Vue | ✅ | ✅ | Vite | - |
68+
| Svelte | ✅ | ✅ | Vite | - |
69+
| SolidJS | ✅ | ✅ | Vite | - |
70+
| Vanilla | ✅ | ✅ | Vite | - |
71+
| Angular | - | ✅ | Angular CLI | - |
72+
| Next.js | ✅ | ✅ | - | React |
73+
| Nuxt | ✅ | ✅ | - | Vue |
74+
| SvelteKit | ✅ | ✅ | - | Svelte |
6775

6876
## 🛠️ Development
6977

70-
Each framework template can be run independently:
78+
Each framework example can be run independently:
7179

7280
```bash
7381
# React JavaScript
74-
cd frameworks/react-js
82+
cd frameworks/react/JS
7583
npm install
7684
npm run dev
7785

78-
# Vue TypeScript
79-
cd frameworks/vue-ts
86+
# Vue TypeScript
87+
cd frameworks/vue/TS
88+
npm install
89+
npm run dev
90+
91+
# SolidJS TypeScript
92+
cd frameworks/solid/ts
93+
npm install
94+
npm run dev
95+
96+
# Next.js JavaScript
97+
cd frameworks/next/JS
8098
npm install
8199
npm run dev
82100
```
83101

84-
## 📚 Usage with CLI Tools
102+
## 📦 Installation Methods
103+
104+
### Frameworks Directory (CDN Installation)
105+
106+
All examples in `frameworks/` use **CDN installation** of Nutrient Web SDK:
107+
108+
```html
109+
<script src="https://cdn.cloud.pspdfkit.com/pspdfkit-web@{VERSION}/nutrient-viewer.js"></script>
110+
```
85111

86-
This repository is designed to work with scaffolding tools like `create-nutrient-app`. The CLI can:
112+
This approach:
87113

88-
1. **Choose Framework**: React, Vue, Angular, etc.
89-
2. **Choose Language**: JavaScript or TypeScript
90-
3. **Choose Example**: Basic viewer, magazine mode, forms, etc.
91-
4. **Generate Project**: Combine framework template + example implementation
114+
- ✅ No build configuration needed
115+
- ✅ Faster initial setup
116+
- ✅ Automatic updates (if using `@latest`)
117+
- ✅ Works in any framework
118+
119+
### Examples Directory (Various Methods)
120+
121+
Examples in `examples/` may use different installation methods:
122+
123+
- Package installation (`npm install`)
124+
- CDN installation
125+
- Framework-specific integrations
126+
127+
## 🔧 Scripts
128+
129+
The repository includes maintenance scripts:
92130

93-
Example CLI usage:
94131
```bash
95-
npx create-nutrient-app my-project --framework react --language ts --example magazine-mode
132+
# Install dependencies in all examples and frameworks
133+
./scripts/install-dependencies.sh
134+
135+
# Run e2e tests
136+
./scripts/e2e-tests.sh
137+
138+
# Update Nutrient SDK versions
139+
./scripts/update-nutrient-in-examples.sh
96140
```
97141

98-
## 🔄 Migration from `examples-old/`
142+
## 🎯 Example Structure
99143

100-
The previous examples have been moved to `examples-old/` for reference. The new architecture provides:
144+
Each framework example follows a consistent pattern:
101145

102-
- **Better separation of concerns**: Framework setup vs. Nutrient features
103-
- **DRY principle**: Reusable examples across all frameworks
104-
- **CLI friendly**: Easy mix-and-match of framework + example
105-
- **Maintainable**: Updates to examples benefit all frameworks
146+
```
147+
frameworks/{framework}/{JS|TS}/
148+
├── src/
149+
│ ├── nutrient/
150+
│ │ ├── nutrient-config.{js|ts} # Shared config
151+
│ │ ├── loadNutrientViewer.{js|ts} # CDN loader
152+
│ │ ├── basic-viewer/
153+
│ │ │ └── implementation.{js|ts} # Basic viewer logic
154+
│ │ ├── magazine-mode/
155+
│ │ │ └── implementation.{js|ts} # Magazine mode logic
156+
│ │ ├── custom-overlays/
157+
│ │ │ └── implementation.{js|ts} # Custom overlays logic
158+
│ │ └── watermarks/
159+
│ │ └── implementation.{js|ts} # Watermarks logic
160+
│ ├── pages/
161+
│ │ ├── HomePage.{jsx|tsx|vue|svelte} # Landing page with links
162+
│ │ ├── BasicViewerPage.{jsx|tsx|vue|svelte}
163+
│ │ ├── MagazineModePage.{jsx|tsx|vue|svelte}
164+
│ │ ├── CustomOverlaysPage.{jsx|tsx|vue|svelte}
165+
│ │ └── WatermarksPage.{jsx|tsx|vue|svelte}
166+
│ └── components/
167+
│ └── logos/ # Framework logos
168+
├── package.json
169+
└── vite.config.{js|ts} # Build configuration
170+
```
106171

107172
## 🤝 Contributing
108173

109-
When adding new examples:
174+
When adding new framework examples:
175+
176+
1. **Follow the naming convention**:
177+
178+
- Use `{framework}/{JS|TS}/` for Vite-based frameworks
179+
- Use `{framework}/{js|ts}/` for framework CLIs (lowercase)
180+
181+
2. **Include all 4 examples**: Basic Viewer, Magazine Mode, Custom Overlays, Watermarks
182+
183+
3. **Use CDN installation**: Keep examples simple and framework-focused
184+
185+
4. **Maintain consistency**:
186+
187+
- Same file structure across all frameworks
188+
- Same implementation logic (just adapted to framework patterns)
189+
- Same styling and UI
190+
191+
5. **Add both JS and TS variants** (where applicable)
192+
193+
## 📚 Additional Resources
194+
195+
- [Nutrient Web SDK Documentation](https://www.nutrient.io/guides/web/)
196+
- [Nutrient Web SDK API Reference](https://www.nutrient.io/guides/web/api/)
197+
- [Nutrient Support](https://www.nutrient.io/support/)
110198

111-
1. **Keep framework-agnostic**: Examples should work with any framework
112-
2. **Focus on Nutrient features**: Let framework templates handle the setup
113-
3. **Document thoroughly**: Include README with usage examples
114-
4. **Export clean API**: Simple functions for load/unload operations
199+
## 📄 License
115200

116-
When adding new frameworks:
117-
1. **Follow naming convention**: `{framework}-{language}/`
118-
2. **Include modern tooling**: Vite, TypeScript support, etc.
119-
3. **Minimal setup**: Just enough to integrate with examples
120-
4. **Consistent patterns**: Follow existing template structure
201+
Examples are provided for demonstration purposes. Check individual example directories for specific license information.

‎scripts/e2e-tests.sh‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
# array of directories to exclude
44
exclude_dirs=("examples/webpack" "examples/blazor" "examples/gatsbyjs" "examples/laravel" "examples/salesforce" "examples/wasm-benchmark" "examples/electron-nodeintegration" "examples/electron" "examples/asp-net")
55

6+
# Test examples/
67
for dir in examples/*; do
78
if [ -d "$dir" ]; then
89
skip=false
@@ -18,3 +19,11 @@ for dir in examples/*; do
1819
fi
1920
fi
2021
done
22+
23+
# Test frameworks/*/*
24+
for dir in frameworks/*/*; do
25+
if [ -d "$dir" ]; then
26+
echo "Running e2e tests in $dir"
27+
(SERVER_DIR="$dir" npm run test)
28+
fi
29+
done

‎scripts/install-dependencies.sh‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
#!/bin/bash
2-
# Runs npm/pnpm install on all examples
2+
# Runs npm/pnpm install on all examples and frameworks
33

44
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
55

6+
# Install dependencies in examples/
67
for dir in examples/*; do
78
if [ -d "$dir" ]; then
89
echo "Installing dependencies in $dir"
@@ -19,3 +20,21 @@ for dir in examples/*; do
1920

2021
fi
2122
done
23+
24+
# Install dependencies in frameworks/*/*
25+
for dir in frameworks/*/*; do
26+
if [ -d "$dir" ]; then
27+
echo "Installing dependencies in $dir"
28+
29+
pushd "${SCRIPT_DIR}/../${dir}/" > /dev/null
30+
31+
if [ -f "pnpm-lock.yaml" ]; then
32+
pnpm install
33+
elif [ -f "package-lock.json" ]; then
34+
npm install
35+
fi
36+
37+
popd > /dev/null
38+
39+
fi
40+
done

0 commit comments

Comments
 (0)