Skip to content

Commit 292d5be

Browse files
thinkdjthinkdj
committed
Create FEATURES.md
1 parent bdf5e8c commit 292d5be

1 file changed

Lines changed: 333 additions & 0 deletions

File tree

‎FEATURES.md‎

Lines changed: 333 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,333 @@
1+
# Choose Features Guide
2+
3+
This Tauri starter kit is **feature-neutral by design**. All optional features are disabled by default, and you choose which features to enable when running or building your application. This keeps your application lightweight and only includes the functionality you actually use.
4+
5+
## Available Features
6+
7+
### 🔔 Notifications (`notifications`)
8+
- **What it includes**: Native system notifications with permission handling
9+
- **Dependencies**: `tauri-plugin-notification`
10+
- **Frontend components**: Notification demo page
11+
- **Use cases**: User alerts, status updates, background task completion
12+
13+
### 🔗 Deep Links (`deep-links`)
14+
- **What it includes**: Custom protocol handling for deep linking
15+
- **Dependencies**: `tauri-plugin-deep-link`
16+
- **Frontend components**: Deep link demo page
17+
- **Use cases**: Opening your app from web browsers, handling custom URLs
18+
19+
### 📋 Clipboard (`clipboard`)
20+
- **What it includes**: Advanced clipboard management with history and image support
21+
- **Dependencies**: `tauri-plugin-clipboard-manager`, `image`, `base64`, `chrono`
22+
- **Frontend components**: Clipboard demo page with full image support
23+
- **Use cases**: Clipboard history like Win+V, image clipboard operations, format analysis
24+
25+
### 🖥️ System Tray (`system-tray`)
26+
- **What it includes**: System tray icon with context menu
27+
- **Dependencies**: Built into Tauri core
28+
- **Frontend components**: Tray menu integration
29+
- **Use cases**: Background operation, quick access menu, minimize to tray
30+
31+
### 🪟 Window Manager (`window-manager`)
32+
- **What it includes**: Inter-window communication, multi-window management, message passing
33+
- **Dependencies**: Built into Tauri core
34+
- **Frontend components**: Window manager demo, window creation interface, message history
35+
- **Use cases**: Multi-window applications, window-to-window messaging, distributed UI components
36+
- **Features**:
37+
- Create and manage multiple windows with custom labels
38+
- Send targeted messages to specific windows
39+
- Broadcast messages to all windows
40+
- Message history tracking with timestamps
41+
- Window state management (focus, visibility, positioning)
42+
- Developer tools integration (restart app in dev mode)
43+
44+
## Default Configuration
45+
46+
By default, **no optional features are enabled** (feature-neutral):
47+
48+
```toml
49+
[features]
50+
default = []
51+
```
52+
53+
This means you get a minimal, lightweight application by default and choose which features to enable when you run or build.
54+
55+
## How to Choose Features
56+
57+
### Method 1: NPM Scripts (Recommended)
58+
59+
Use the provided npm scripts to run or build with specific features:
60+
61+
```bash
62+
# Development with features
63+
npm run tauri:dev -- --features clipboard,notifications
64+
npm run tauri:dev -- --features deep-links
65+
npm run tauri:dev:feat # All features enabled
66+
67+
# Development with no features (minimal)
68+
npm run tauri:dev
69+
70+
# Building with features
71+
npm run tauri:build -- --features clipboard,notifications
72+
npm run tauri:build -- --features deep-links
73+
74+
# Building with no features (minimal)
75+
npm run tauri:build
76+
```
77+
78+
### Method 2: Direct Cargo Commands
79+
80+
You can also use cargo directly:
81+
82+
```bash
83+
# Development with features
84+
cargo tauri dev --features clipboard,notifications
85+
cargo tauri dev --features deep-links
86+
87+
# Building with features
88+
cargo tauri build --features clipboard,notifications
89+
cargo tauri build --features deep-links
90+
91+
# Minimal builds (no features)
92+
cargo tauri dev
93+
cargo tauri build
94+
```
95+
96+
### Method 3: Modify Cargo.toml (Not Recommended)
97+
98+
While you can still modify the default features in `src-tauri/Cargo.toml`, this approach is discouraged as it makes the project less flexible:
99+
100+
```toml
101+
# Not recommended - makes project less flexible
102+
[features]
103+
default = ["clipboard", "notifications"]
104+
```
105+
106+
**Why not recommended?** Because it forces everyone using your project to have the same features, whereas the command-line approach lets each developer choose what they need.
107+
108+
## Feature Combinations
109+
110+
### Minimal Build (Default)
111+
```bash
112+
npm run tauri:dev
113+
npm run tauri:build
114+
```
115+
- Smallest bundle size
116+
- Only basic window management
117+
- No external plugin dependencies
118+
119+
### Essential Build
120+
```bash
121+
npm run tauri:dev -- --features notifications,system-tray
122+
npm run tauri:build -- --features notifications,system-tray
123+
```
124+
- Basic notifications
125+
- System tray integration
126+
- Good for simple desktop apps
127+
128+
### Power User Build
129+
```bash
130+
npm run tauri:dev -- --features clipboard,notifications
131+
npm run tauri:build -- --features clipboard,notifications
132+
```
133+
- Advanced clipboard management
134+
- System notifications
135+
- Great for productivity apps
136+
137+
### Full Build
138+
```bash
139+
npm run tauri:dev:feat # Shortcut for all features
140+
npm run tauri:dev -- --features notifications,deep-links,clipboard,system-tray,window-manager
141+
npm run tauri:build -- --features notifications,deep-links,clipboard,system-tray,window-manager
142+
```
143+
- All features enabled
144+
- Complete functionality
145+
- Larger bundle size
146+
147+
## Frontend Integration
148+
149+
The frontend **automatically detects** which features are enabled and shows/hides components accordingly. No manual configuration needed!
150+
151+
### Automatic Feature Detection
152+
153+
The application uses SWR to fetch enabled features from the Rust backend:
154+
155+
```tsx
156+
// This happens automatically in src/app/page.tsx
157+
const { data: features } = useSWR('tauri-features', fetchFeatures)
158+
159+
// Components are conditionally rendered:
160+
{features?.has('clipboard') && <ClipboardDemo />}
161+
{features?.has('notifications') && <NotificationDemo />}
162+
{features?.has('deep-links') && <DeepLinkDemo />}
163+
{features?.has('window-manager') && <WindowManagerDemo />}
164+
```
165+
166+
### What This Means
167+
168+
- **No manual updates needed**: When you run with different features, the UI automatically adapts
169+
- **Clean experience**: Users only see features that are actually available
170+
- **No broken links**: Demo pages only appear when their features are enabled
171+
- **Helpful messaging**: When no features are enabled, users see guidance on how to enable them
172+
173+
### Example Behavior
174+
175+
```bash
176+
# Run with no features - shows minimal UI with helpful message
177+
npm run tauri:dev
178+
179+
# Run with clipboard only - shows only clipboard demo
180+
npm run tauri:dev -- --features clipboard
181+
182+
# Run with all features - shows all demos
183+
npm run tauri:dev:feat
184+
```
185+
186+
## Bundle Size Impact
187+
188+
Approximate bundle size impact of each feature:
189+
190+
| Feature | Size Impact | Dependencies |
191+
|---------|-------------|--------------|
192+
| `notifications` | ~200KB | tauri-plugin-notification |
193+
| `deep-links` | ~150KB | tauri-plugin-deep-link |
194+
| `clipboard` | ~800KB | tauri-plugin-clipboard-manager + image processing |
195+
| `system-tray` | ~50KB | Built into Tauri |
196+
| `window-manager` | ~100KB | Built into Tauri core |
197+
198+
## Development Workflow
199+
200+
### 1. Start Development
201+
Simply run with the features you want to test:
202+
```bash
203+
# Start with specific features
204+
npm run tauri:dev -- --features clipboard,notifications
205+
206+
# Or start minimal and add features as needed
207+
npm run tauri:dev
208+
```
209+
210+
### 2. Test Different Combinations
211+
Easily test different feature combinations without changing code:
212+
```bash
213+
# Test minimal build
214+
npm run tauri:dev
215+
216+
# Test with clipboard only
217+
npm run tauri:dev -- --features clipboard
218+
219+
# Test full build
220+
npm run tauri:dev:feat
221+
```
222+
223+
### 3. Build for Production
224+
Build with the exact features your users need:
225+
```bash
226+
npm run tauri:build -- --features clipboard,notifications
227+
```
228+
229+
### 4. No Manual Updates Needed
230+
The frontend automatically adapts to enabled features - no code changes required!
231+
232+
## Common Configurations
233+
234+
### Blog/Content App
235+
```bash
236+
npm run tauri:dev -- --features notifications,system-tray
237+
npm run tauri:build -- --features notifications,system-tray
238+
```
239+
240+
### Productivity/Utility App
241+
```bash
242+
npm run tauri:dev -- --features clipboard,notifications,system-tray
243+
npm run tauri:build -- --features clipboard,notifications,system-tray
244+
```
245+
246+
### Web Integration App
247+
```bash
248+
npm run tauri:dev -- --features deep-links,notifications
249+
npm run tauri:build -- --features deep-links,notifications
250+
```
251+
252+
### Multi-Window App
253+
```bash
254+
npm run tauri:dev -- --features window-manager,notifications,system-tray
255+
npm run tauri:build -- --features window-manager,notifications,system-tray
256+
```
257+
258+
### Minimal Utility
259+
```bash
260+
npm run tauri:dev -- --features system-tray
261+
npm run tauri:build -- --features system-tray
262+
```
263+
264+
## Troubleshooting
265+
266+
### Build Errors After Disabling Features
267+
268+
If you get build errors after disabling features:
269+
270+
1. **Clean the build**: `cargo clean`
271+
2. **Check imports**: Remove imports for disabled features in `main.rs`
272+
3. **Update frontend**: Remove references to disabled Tauri commands
273+
274+
### Runtime Errors
275+
276+
If you get runtime errors:
277+
278+
1. **Check frontend calls**: Ensure frontend doesn't call disabled Tauri commands
279+
2. **Conditional rendering**: Use feature flags in frontend to conditionally show UI
280+
3. **Error handling**: Add proper error handling for missing features
281+
282+
## Advanced: Custom NPM Scripts
283+
284+
You can create your own custom npm scripts for common feature combinations in `package.json`:
285+
286+
```json
287+
{
288+
"scripts": {
289+
"tauri:dev:productivity": "tauri dev --features clipboard,notifications,system-tray",
290+
"tauri:dev:web": "tauri dev --features deep-links,notifications",
291+
"tauri:dev:multiwindow": "tauri dev --features window-manager,notifications,system-tray",
292+
"tauri:build:productivity": "tauri build --features clipboard,notifications,system-tray",
293+
"tauri:build:web": "tauri build --features deep-links,notifications",
294+
"tauri:build:multiwindow": "tauri build --features window-manager,notifications,system-tray"
295+
}
296+
}
297+
```
298+
299+
Then use them:
300+
```bash
301+
npm run tauri:dev:productivity
302+
npm run tauri:build:web
303+
```
304+
305+
### Custom Cargo Features (Advanced)
306+
307+
If you need more complex feature combinations, you can still define custom features in `src-tauri/Cargo.toml`:
308+
309+
```toml
310+
[features]
311+
# Custom combinations
312+
productivity = ["clipboard", "notifications", "system-tray"]
313+
web-integration = ["deep-links", "notifications"]
314+
multi-window = ["window-manager", "notifications", "system-tray"]
315+
316+
# Individual features (already defined)
317+
clipboard = ["dep:tauri-plugin-clipboard-manager", "dep:image", "dep:base64", "dep:chrono"]
318+
notifications = ["dep:tauri-plugin-notification"]
319+
window-manager = [] # Built into Tauri core
320+
# ... etc
321+
```
322+
323+
Then use them:
324+
```bash
325+
npm run tauri:dev -- --features productivity
326+
cargo tauri build --features web-integration
327+
```
328+
329+
## Need Help?
330+
331+
- Check the [Tauri documentation](https://tauri.app/v1/guides/)
332+
- Review the source code in `src-tauri/src/` for implementation details
333+
- Look at the demo pages for usage examples

0 commit comments

Comments
 (0)