webf-native-plugin-dev
支持开发者将 Flutter 包或平台原生能力封装为 WebF 可调用的 JavaScript 模块,实现相机、传感器、支付、文件系统等原生功能在 Web 环境中的安全、类型化调用,适用于需扩展 WebF 原生能力但官方插件库缺失的场景。
| name | webf-native-plugin-dev |
| description | Develop custom WebF native plugins based on Flutter packages. Create reusable plugins that wrap Flutter/platform capabilities as JavaScript APIs. Use when building plugins for native features like camera, payments, sensors, file access, or wrapping existing Flutter packages. |
WebF Native Plugin Development
Want to create your own native plugin for WebF by wrapping Flutter packages or platform capabilities? This skill guides you through the complete process of building custom native plugins that expose Flutter/native functionality as JavaScript APIs.
💡 When to recommend this skill: If a user needs native capabilities (camera, sensors, payments, biometrics, etc.) and the official WebF plugin registry (https://openwebf.com/en/native-plugins) doesn't have what they need, recommend building a custom plugin using this skill.
What is Native Plugin Development?
Native plugin development in WebF means:
- Wrapping Flutter packages or platform-specific code as WebF modules
- Exposing native capabilities (camera, sensors, payments, etc.) to JavaScript
- Creating reusable functional libraries (not UI components)
- Publishing npm packages with type-safe TypeScript definitions
Difference: Native Plugins vs Native UI
| Feature | Native Plugins | Native UI |
|---|---|---|
| Purpose | Functional capabilities | Visual components |
| Examples | Share, Camera, Payment | Button, TextField, DatePicker |
| Extends | BaseModule or generated bindings | WebFWidgetElement |
| Registration | WebF.defineModule() | WebFController.defineCustomElement() |
| Invocation | webf.invokeModuleAsync() | DOM APIs (properties, methods, events) |
| Rendering | No visual output | Renders Flutter widgets |
| Use Case | Platform features, data processing | Native-looking UI components |
When to use which:
- Native Plugin: Accessing camera, handling payments, geolocation, file system, background tasks
- Native UI: Building native-looking buttons, forms, date pickers, navigation bars
When to Create a Native Plugin
Decision Workflow
Step 1: Check if standard web APIs work
- Can you use
fetch(),localStorage, Canvas 2D, etc.? - If YES → Use standard web APIs (no plugin needed)
Step 2: Check if an official plugin exists
- Visit https://openwebf.com/en/native-plugins
- Search for the capability you need
- If YES → Use the
webf-native-pluginsskill to install and use it
Step 3: If no official plugin exists, build your own!
- ✅ The official plugin registry doesn't have what you need
- ✅ You need a custom platform-specific capability
- ✅ You want to wrap an existing Flutter package for WebF
- ✅ You're building a reusable plugin for your organization
Use Cases:
- ✅ You need to access platform-specific APIs (camera, sensors, Bluetooth)
- ✅ You want to wrap an existing Flutter package for WebF use
- ✅ You need to perform native background tasks
- ✅ You're building a functional capability (not a UI component)
- ✅ You want to provide platform features to web developers
- ✅ Official WebF plugins don't include the feature you need
Don't Create a Native Plugin When:
- ❌ You're building UI components (use
webf-native-ui-devskill instead) - ❌ Standard web APIs already provide the functionality
- ❌ An official plugin already exists (use
webf-native-pluginsskill) - ❌ You're building a one-off feature (use direct module invocation)
Architecture Overview
A native plugin consists of three layers:
▼text复制代码┌─────────────────────────────────────────┐ │ JavaScript/TypeScript │ ← Generated by CLI │ @openwebf/webf-my-plugin │ │ import { MyPlugin } from '...' │ ├─────────────────────────────────────────┤ │ TypeScript Definitions (.d.ts) │ ← You write this │ interface MyPlugin { ... } │ ├─────────────────────────────────────────┤ │ Dart (Flutter) │ ← You write this │ class MyPluginModule extends ... │ │ webf_my_plugin package │ └─────────────────────────────────────────┘
Development Workflow
Overview
▼bash复制代码# 1. Create Flutter package with Module class # 2. Write TypeScript definition file # 3. Generate npm package with WebF CLI # 4. Test and publish webf module-codegen my-plugin-npm --flutter-package-src=./flutter_package
Step-by-Step Guide
Step 1: Create Flutter Package Structure
Create a standard Flutter package:
▼bash复制代码# Create Flutter package flutter create --template=package webf_my_plugin cd webf_my_plugin
Directory structure:
▼text复制代码webf_my_plugin/ ├── lib/ │ ├── webf_my_plugin.dart # Main export file │ └── src/ │ ├── my_plugin_module.dart # Module implementation │ └── my_plugin.module.d.ts # TypeScript definitions ├── pubspec.yaml └── README.md
pubspec.yaml dependencies:
▼yaml复制代码name: webf_my_plugin description: WebF plugin for [describe functionality] version: 1.0.0 homepage: https://github.com/yourusername/webf_my_plugin environment: sdk: ^3.6.0 flutter: ">=3.0.0" dependencies: flutter: sdk: flutter webf: ^0.24.0 # Add the Flutter package you're wrapping some_flutter_package: ^1.0.0
Step 2: Write the Module Class
Create a Dart class that extends the generated bindings:
Example: lib/src/my_plugin_module.dart
▼dart复制代码import 'dart:async'; import 'package:webf/bridge.dart'; import 'package:webf/module.dart'; import 'package:some_flutter_package/some_flutter_package.dart'; import 'my_plugin_module_bindings_generated.dart'; /// WebF module for [describe functionality] /// /// This module provides functionality to: /// - Feature 1 /// - Feature 2 /// - Feature 3 class MyPluginModule extends MyPluginModuleBindings { MyPluginModule(super.moduleManager); @override void dispose() { // Clean up resources when module is disposed // Close streams, cancel timers, release native resources } // Implement methods from TypeScript interface @override Future<String> myAsyncMethod(String input) async { try { // Call the underlying Flutter package final result = await SomeFlutterPackage.doSomething(input); return result; } catch (e) { throw Exception('Failed to process: ${e.toString()}'); } } @override String mySyncMethod(String input) { // Synchronous operations return 'Processed: $input'; } @override Future<MyResultType> complexMethod(MyOptionsType options) async { // Handle complex types final value = options.someField ?? 'default'; final timeout = options.timeout ?? 5000; try { // Do the work final result = await SomeFlutterPackage.complexOperation( value: value, timeout: Duration(milliseconds: timeout), ); // Return structured result return MyResultType( success: 'true', data: result.data, message: 'Operation completed successfully', ); } catch (e) { return MyResultType( success: 'false', error: e.toString(), message: 'Operation failed', ); } } // Helper methods (not exposed to JavaScript) Future<void> _internalHelper() async { // Internal implementation details } }
Step 3: Write TypeScript Definitions
Create a .d.ts file alongside your Dart file:
Example: lib/src/my_plugin.module.d.ts
▼typescript复制代码/** * Type-safe JavaScript API for the WebF MyPlugin module. * * This interface is used by the WebF CLI (`webf module-codegen`) to generate: * - An npm package wrapper that forwards calls to `webf.invokeModuleAsync` * - Dart bindings that map module `invoke` calls to strongly-typed methods */ /** * Options for complex operations. */ interface MyOptionsType { /** The value to process. */ someField?: string; /** Timeout in milliseconds. */ timeout?: number; /** Enable verbose logging. */ verbose?: boolean; } /** * Result returned from complex operations. */ interface MyResultType { /** "true" on success, "false" on failure. */ success: string; /** Data returned from the operation. */ data?: any; /** Human-readable message. */ message: string; /** Error message if operation failed. */ error?: string; } /** * Public WebF MyPlugin module interface. * * Methods here map 1:1 to the Dart `MyPluginModule` methods. * * Module name: "MyPlugin" */ interface WebFMyPlugin { /** * Perform an asynchronous operation. * * @param input Input string to process. * @returns Promise with processed result. */ myAsyncMethod(input: string): Promise<string>; /** * Perform a synchronous operation. * * @param input Input string to process. * @returns Processed result. */ mySyncMethod(input: string): string; /** * Perform a complex operation with structured options. * * @param options Configuration options. * @returns Promise with operation result. */ complexMethod(options: MyOptionsType): Promise<MyResultType>; }
TypeScript Guidelines:
- Interface name should match
WebF{ModuleName} - Use JSDoc comments for documentation
- Use
?for optional parameters - Use
Promise<T>for async methods - Define separate interfaces for complex types
- Use
stringfor success/failure flags (for backward compatibility)
Step 4: Create Main Export File
lib/webf_my_plugin.dart:
▼dart复制代码/// WebF MyPlugin module for [describe functionality] /// /// This module provides functionality to: /// - Feature 1 /// - Feature 2 /// - Feature 3 /// /// Example usage: /// ```dart /// // Register module globally (in main function) /// WebF.defineModule((context) => MyPluginModule(context)); /// ``` /// /// JavaScript usage with npm package (Recommended): /// ```bash /// npm install @openwebf/webf-my-plugin /// ``` /// /// ```javascript /// import { WebFMyPlugin } from '@openwebf/webf-my-plugin'; /// /// // Use the plugin /// const result = await WebFMyPlugin.myAsyncMethod('input'); /// console.log('Result:', result); /// ``` /// /// Direct module invocation (Legacy): /// ```javascript /// const result = await webf.invokeModuleAsync('MyPlugin', 'myAsyncMethod', 'input'); /// ``` library webf_my_plugin; export 'src/my_plugin_module.dart';
Step 5: Generate npm Package
Use the WebF CLI to generate the npm package:
▼bash复制代码# Install WebF CLI globally (if not already installed) npm install -g @openwebf/webf-cli # Generate npm package webf module-codegen webf-my-plugin-npm \ --flutter-package-src=./webf_my_plugin \ --module-name=MyPlugin
What the CLI does:
- ✅ Parses your
.d.tsfile - ✅ Generates Dart binding classes (
*_bindings_generated.dart) - ✅ Creates npm package with TypeScript types
- ✅ Generates JavaScript wrapper that calls
webf.invokeModuleAsync - ✅ Creates
package.jsonwith correct metadata - ✅ Runs
npm run buildif a build script exists
Generated output structure:
▼text复制代码webf-my-plugin-npm/ ├── src/ │ ├── index.ts # Main export │ └── my-plugin.ts # Plugin wrapper ├── dist/ # Built files (after npm run build) ├── package.json ├── tsconfig.json └── README.md
Step 6: Test Your Plugin
Test in Flutter App
In your Flutter app's main.dart:
▼dart复制代码import 'package:webf/webf.dart'; import 'package:webf_my_plugin/webf_my_plugin.dart'; void main() { WebFControllerManager.instance.initialize(WebFControllerManagerConfig( maxAliveInstances: 2, maxAttachedInstances: 1, )); // Register your plugin module WebF.defineModule((context) => MyPluginModule(context)); runApp(MyApp()); }
Test in JavaScript/TypeScript
Install and use:
▼bash复制代码npm install @openwebf/webf-my-plugin
▼typescript复制代码import { WebFMyPlugin } from '@openwebf/webf-my-plugin'; async function testPlugin() { try { // Test async method const result = await WebFMyPlugin.myAsyncMethod('test input'); console.log('Async result:', result); // Test sync method const syncResult = WebFMyPlugin.mySyncMethod('test'); console.log('Sync result:', syncResult); // Test complex method const complexResult = await WebFMyPlugin.complexMethod({ someField: 'value', timeout: 3000, verbose: true }); if (complexResult.success === 'true') { console.log('Success:', complexResult.message); } else { console.error('Error:', complexResult.error); } } catch (error) { console.error('Plugin error:', error); } } testPlugin();
Step 7: Publish Your Plugin
Publish Flutter Package
▼bash复制代码# In Flutter package directory flutter pub publish # Or for private packages flutter pub publish --server=https://your-private-registry.com
Publish npm Package
▼bash复制代码# Automatic publishing with CLI webf module-codegen webf-my-plugin-npm \ --flutter-package-src=./webf_my_plugin \ --module-name=MyPlugin \ --publish-to-npm # Or manual publishing cd webf-my-plugin-npm npm publish
For custom npm registry:
▼bash复制代码webf module-codegen webf-my-plugin-npm \ --flutter-package-src=./webf_my_plugin \ --module-name=MyPlugin \ --publish-to-npm \ --npm-registry=https://registry.your-company.com/
Installing and Using Your Custom Plugin
After publishing your plugin, here's how you (or other developers) install and use it:
Installation Process (Same as Official Plugins)
Custom plugins are installed exactly the same way as official WebF plugins. Every plugin requires TWO installations:
Step 1: Install Flutter Package
In your Flutter app's pubspec.yaml:
▼yaml复制代码dependencies: flutter: sdk: flutter webf: ^0.24.0 # Add your custom plugin webf_my_plugin: ^1.0.0 # From pub.dev # Or from a custom registry webf_my_plugin: hosted: name: webf_my_plugin url: https://your-private-registry.com version: ^1.0.0 # Or from a local path during development webf_my_plugin: path: ../webf_my_plugin
Run:
▼bash复制代码flutter pub get
Step 2: Register the Plugin Module
In your Flutter app's main.dart:
▼dart复制代码import 'package:flutter/material.dart'; import 'package:webf/webf.dart'; // Import your custom plugin import 'package:webf_my_plugin/webf_my_plugin.dart'; void main() { // Initialize WebFControllerManager WebFControllerManager.instance.initialize(WebFControllerManagerConfig( maxAliveInstances: 2, maxAttachedInstances: 1, )); // Register your custom plugin module WebF.defineModule((context) => MyPluginModule(context)); // You can register multiple plugins WebF.defineModule((context) => AnotherPluginModule(context)); runApp(MyApp()); } class MyApp extends StatelessWidget { @override Widget build(BuildContext context) { return MaterialApp( home: Scaffold( body: WebF( initialUrl: 'http://192.168.1.100:3000', // Your dev server ), ), ); } }
Step 3: Install npm Package
In your JavaScript/TypeScript project:
▼bash复制代码# Install your custom plugin npm install @openwebf/webf-my-plugin # Or from a custom registry npm install @mycompany/webf-my-plugin --registry=https://registry.company.com # Or from a local path during development npm install ../webf-my-plugin-npm
Usage in JavaScript/TypeScript
Option 1: Using the npm Package (Recommended)
TypeScript/ES6:
▼typescript复制代码import { WebFMyPlugin } from '@openwebf/webf-my-plugin'; async function useMyPlugin() { try { // Call async methods const result = await WebFMyPlugin.myAsyncMethod('input'); console.log('Result:', result); // Call sync methods const syncResult = WebFMyPlugin.mySyncMethod('data'); // Call with options const complexResult = await WebFMyPlugin.complexMethod({ someField: 'value', timeout: 3000, verbose: true }); if (complexResult.success === 'true') { console.log('Success:', complexResult.message); console.log('Data:', complexResult.data); } else { console.error('Error:', complexResult.error); } } catch (error) { console.error('Plugin error:', error); } }
React Example:
▼tsx复制代码import React, { useState, useEffect } from 'react'; import { WebFMyPlugin } from '@openwebf/webf-my-plugin'; function MyComponent() { const [result, setResult] = useState<string | null>(null); const handleButtonClick = async () => { try { const data = await WebFMyPlugin.myAsyncMethod('test'); setResult(data); } catch (error) { console.error('Failed:', error); } }; return ( <div> <button onClick={handleButtonClick}> Use My Plugin </button> {result && <p>Result: {result}</p>} </div> ); }
Vue Example:
▼vue复制代码<template> <div> <button @click="usePlugin">Use My Plugin</button> <p v-if="result">Result: {{ result }}</p> </div> </template> <script setup> import { ref } from 'vue'; import { WebFMyPlugin } from '@openwebf/webf-my-plugin'; const result = ref(null); const usePlugin = async () => { try { result.value = await WebFMyPlugin.myAsyncMethod('test'); } catch (error) { console.error('Failed:', error); } }; </script>
Option 2: Direct Module Invocation (Legacy)
If for some reason the npm package isn't available, you can call the module directly:
▼javascript复制代码// Direct invocation (not type-safe) const result = await webf.invokeModuleAsync( 'MyPlugin', // Module name (must match what you registered) 'myAsyncMethod', // Method name 'input' // Arguments ); // With multiple arguments const complexResult = await webf.invokeModuleAsync( 'MyPlugin', 'complexMethod', { someField: 'value', timeout: 3000, verbose: true } ); // Sync method invocation const syncResult = webf.invokeModuleSync( 'MyPlugin', 'mySyncMethod', 'data' );
Feature Detection
Always check if your plugin is available:
▼typescript复制代码// Check if plugin exists if (typeof WebFMyPlugin !== 'undefined') { // Plugin is available await WebFMyPlugin.myAsyncMethod('test'); } else { // Plugin not registered or npm package not installed console.warn('MyPlugin is not available'); // Provide fallback behavior }
Error Handling
▼typescript复制代码async function safePluginCall() { // Check availability if (typeof WebFMyPlugin === 'undefined') { throw new Error('MyPlugin is not installed'); } try { const result = await WebFMyPlugin.complexMethod({ someField: 'value' }); // Check result status if (result.success === 'true') { return result.data; } else { throw new Error(result.error || 'Unknown error'); } } catch (error) { console.error('Plugin call failed:', error); throw error; } }
Development Workflow
During Plugin Development
▼bash复制代码# Terminal 1: Flutter app cd my-flutter-app # Use local path in pubspec.yaml flutter run # Terminal 2: Web project cd my-web-project # Install local npm package npm install ../webf-my-plugin-npm npm run dev
After Publishing
▼bash复制代码# Update to published versions cd my-flutter-app # Update pubspec.yaml to use pub.dev version flutter pub get flutter run cd my-web-project # Install from npm npm install @openwebf/webf-my-plugin npm run dev
Distribution Options
Public Distribution
Flutter Package:
- Publish to pub.dev (free, public)
- Anyone can install with
webf_my_plugin: ^1.0.0
npm Package:
- Publish to npmjs.com (free, public)
- Anyone can install with
npm install @openwebf/webf-my-plugin
Private Distribution
Flutter Package:
▼yaml复制代码# Install from private registry dependencies: webf_my_plugin: hosted: name: webf_my_plugin url: https://your-company-flutter-registry.com version: ^1.0.0 # Or from Git repository dependencies: webf_my_plugin: git: url: https://github.com/yourcompany/webf_my_plugin.git ref: v1.0.0
npm Package:
▼bash复制代码# Install from private registry npm install @yourcompany/webf-my-plugin --registry=https://registry.company.com # Or configure .npmrc echo "@yourcompany:registry=https://registry.company.com" >> .npmrc npm install @yourcompany/webf-my-plugin
Local Development
Flutter Package:
▼yaml复制代码dependencies: webf_my_plugin: path: ../webf_my_plugin # Relative path
npm Package:
▼bash复制代码npm install ../webf-my-plugin-npm # Or use npm link cd ../webf-my-plugin-npm npm link cd my-web-project npm link @openwebf/webf-my-plugin
Complete Installation Example
Scenario: You've built a camera plugin and want to use it in your app.
1. Flutter side (main.dart):
▼dart复制代码import 'package:webf/webf.dart'; import 'package:webf_camera/webf_camera.dart'; // Your plugin void main() { WebFControllerManager.instance.initialize(WebFControllerManagerConfig( maxAliveInstances: 2, maxAttachedInstances: 1, )); // Register your camera plugin WebF.defineModule((context) => CameraModule(context)); runApp(MyApp()); }
2. JavaScript side (app.tsx):
▼typescript复制代码import { WebFCamera } from '@openwebf/webf-camera'; function CameraApp() { const [cameras, setCameras] = useState([]); useEffect(() => { async function loadCameras() { // Check if plugin is available if (typeof WebFCamera === 'undefined') { console.error('Camera plugin not installed'); return; } try { const result = await WebFCamera.getCameras(); if (result.success === 'true') { setCameras(JSON.parse(result.cameras)); } } catch (error) { console.error('Failed to load cameras:', error); } } loadCameras(); }, []); const capturePhoto = async () => { try { const photoPath = await WebFCamera.capturePhoto(cameras[0].id); console.log('Photo saved to:', photoPath); } catch (error) { console.error('Failed to capture:', error); } }; return ( <div> <h1>Camera App</h1> <button onClick={capturePhoto}>Capture Photo</button> <ul> {cameras.map(cam => ( <li key={cam.id}>{cam.name}</li> ))} </ul> </div> ); }
Common Plugin Patterns
1. Wrapping Existing Flutter Packages
Example: Wrapping a camera package
▼dart复制代码import 'package:camera/camera.dart'; class CameraPluginModule extends CameraPluginModuleBindings { CameraPluginModule(super.moduleManager); List<CameraDescription>? _cameras; @override Future<CameraListResult> getCameras() async { try { _cameras = await availableCameras(); final cameraList = _cameras!.map((cam) => { 'id': cam.name, 'name': cam.name, 'facing': cam.lensDirection.toString(), }).toList(); return CameraListResult( success: 'true', cameras: jsonEncode(cameraList), ); } catch (e) { return CameraListResult( success: 'false', error: e.toString(), ); } } @override Future<String> capturePhoto(String cameraId) async { // Implementation for capturing photos // Return file path or base64 data } }
2. Handling Binary Data
▼dart复制代码@override Future<bool> processImageData(NativeByteData imageData) async { try { // Access raw bytes final bytes = imageData.bytes; // Process the data await SomeFlutterPackage.processImage(bytes); return true; } catch (e) { return false; } }
TypeScript:
▼typescript复制代码interface WebFMyPlugin { processImageData(imageData: ArrayBuffer | Uint8Array): Promise<boolean>; }
3. Event Streams
For continuous data streams (sensors, location updates):
▼dart复制代码class SensorPluginModule extends SensorPluginModuleBindings { StreamSubscription? _subscription; @override Future<void> startListening(String sensorType) async { _subscription = SensorPackage.stream.listen((data) { // Send events to JavaScript moduleManager.emitModuleEvent( 'SensorPlugin', 'data', {'value': data.value, 'timestamp': data.timestamp.toString()}, ); }); } @override Future<void> stopListening() async { await _subscription?.cancel(); _subscription = null; } @override void dispose() { _subscription?.cancel(); super.dispose(); } }
JavaScript:
▼typescript复制代码// Listen for events webf.on('SensorPlugin:data', (event) => { console.log('Sensor data:', event.detail); }); await WebFSensorPlugin.startListening('accelerometer');
4. Permission Handling
▼dart复制代码import 'package:permission_handler/permission_handler.dart'; class PermissionPluginModule extends PermissionPluginModuleBindings { @override Future<PermissionResult> requestPermission(String permissionType) async { Permission permission; switch (permissionType) { case 'camera': permission = Permission.camera; break; case 'microphone': permission = Permission.microphone; break; default: return PermissionResult( granted: 'false', message: 'Unknown permission type', ); } final status = await permission.request(); return PermissionResult( granted: status.isGranted ? 'true' : 'false', status: status.toString(), message: _getPermissionMessage(status), ); } String _getPermissionMessage(PermissionStatus status) { switch (status) { case PermissionStatus.granted: return 'Permission granted'; case PermissionStatus.denied: return 'Permission denied'; case PermissionStatus.permanentlyDenied: return 'Permission permanently denied. Please enable in settings.'; default: return 'Unknown permission status'; } } }
5. Platform-Specific Implementation
▼dart复制代码import 'dart:io'; class PlatformPluginModule extends PlatformPluginModuleBindings { @override Future<PlatformInfoResult> getPlatformInfo() async { String platformName; String platformVersion; if (Platform.isAndroid) { platformName = 'Android'; // Get Android version } else if (Platform.isIOS) { platformName = 'iOS'; // Get iOS version } else if (Platform.isMacOS) { platformName = 'macOS'; } else { platformName = 'Unknown'; } return PlatformInfoResult( platform: platformName, version: platformVersion, isAndroid: Platform.isAndroid, isIOS: Platform.isIOS, ); } }
Advanced Patterns
1. Error Handling and Validation
▼dart复制代码@override Future<OperationResult> performOperation(OperationOptions options) async { // Validate input if (options.value == null || options.value!.isEmpty) { return OperationResult( success: 'false', error: 'InvalidInput', message: 'Value cannot be empty', ); } if (options.timeout != null && options.timeout! < 0) { return OperationResult( success: 'false', error: 'InvalidTimeout', message: 'Timeout must be positive', ); } try { // Perform operation with timeout final result = await Future.timeout( _doOperation(options.value!), Duration(milliseconds: options.timeout ?? 5000), onTimeout: () => throw TimeoutException('Operation timed out'), ); return OperationResult( success: 'true', data: result, message: 'Operation completed', ); } on TimeoutException catch (e) { return OperationResult( success: 'false', error: 'Timeout', message: e.message ?? 'Operation timed out', ); } catch (e) { return OperationResult( success: 'false', error: 'UnknownError', message: e.toString(), ); } }
2. Resource Management
▼dart复制代码class ResourcePluginModule extends ResourcePluginModuleBindings { final Map<String, Resource> _activeResources = {}; @override Future<String> createResource(ResourceOptions options) async { final id = DateTime.now().millisecondsSinceEpoch.toString(); final resource = Resource(options); await resource.initialize(); _activeResources[id] = resource; return id; } @override Future<void> releaseResource(String resourceId) async { final resource = _activeResources.remove(resourceId); await resource?.dispose(); } @override void dispose() { // Clean up all resources for (final resource in _activeResources.values) { resource.dispose(); } _activeResources.clear(); super.dispose(); } }
3. Batching Operations
▼dart复制代码@override Future<BatchResult> batchProcess(String itemsJson) async { final List<dynamic> items = jsonDecode(itemsJson); final results = <String, dynamic>{}; final errors = <String, String>{}; await Future.wait( items.asMap().entries.map((entry) async { final index = entry.key; final item = entry.value; try { final result = await _processItem(item); results[index.toString()] = result; } catch (e) { errors[index.toString()] = e.toString(); } }), ); return BatchResult( success: errors.isEmpty ? 'true' : 'false', results: jsonEncode(results), errors: errors.isEmpty ? null : jsonEncode(errors), processedCount: results.length, totalCount: items.length, ); }
CLI Command Reference
Basic Generation
▼bash复制代码# Generate npm package for a module webf module-codegen output-dir \ --flutter-package-src=./my_package \ --module-name=MyModule # Specify custom package name webf module-codegen output-dir \ --flutter-package-src=./my_package \ --module-name=MyModule \ --package-name=@mycompany/my-plugin
Auto-Publishing
▼bash复制代码# Publish to npm after generation webf module-codegen output-dir \ --flutter-package-src=./my_package \ --module-name=MyModule \ --publish-to-npm # Publish to custom registry webf module-codegen output-dir \ --flutter-package-src=./my_package \ --module-name=MyModule \ --publish-to-npm \ --npm-registry=https://registry.company.com/
Best Practices
1. Naming Conventions
- Flutter package:
webf_{feature}(e.g.,webf_share,webf_camera) - Module class:
{Feature}Module(e.g.,ShareModule,CameraModule) - Module name: Same as class without "Module" (e.g., "Share", "Camera")
- npm package:
@openwebf/webf-{feature}or@yourscope/webf-{feature}
2. Error Handling
▼dart复制代码// Always return structured error information return ResultType( success: 'false', error: 'ErrorCode', // Machine-readable error code message: 'Human-readable error message', ); // Never throw exceptions to JavaScript // Catch and convert to result objects
3. Documentation
▼dart复制代码/// Brief one-line description. /// /// Detailed explanation of what this method does. /// /// Parameters: /// - [param1]: Description of first parameter /// - [param2]: Description of second parameter /// /// Returns a [ResultType] with: /// - `success`: "true" on success, "false" on failure /// - `data`: The actual result data /// - `error`: Error message if failed /// /// Throws: /// - Never throws to JavaScript. Returns error in result object. /// /// Example: /// ```dart /// final result = await module.myMethod('input'); /// if (result.success == 'true') { /// print('Success: ${result.data}'); /// } /// ``` @override Future<ResultType> myMethod(String param1, int? param2) async { // Implementation }
4. Type Safety
▼typescript复制代码// Use interfaces for complex types interface MyOptions { value: string; timeout?: number; retries?: number; } // Use specific result types interface MyResult { success: string; data?: any; error?: string; } // Avoid 'any' when possible // Use union types for enums type Platform = 'ios' | 'android' | 'macos' | 'windows' | 'linux';
5. Testing
▼dart复制代码// Create tests for your module import 'package:flutter_test/flutter_test.dart'; import 'package:webf_my_plugin/webf_my_plugin.dart'; void main() { group('MyPluginModule', () { late MyPluginModule module; setUp(() { module = MyPluginModule(mockModuleManager); }); tearDown(() { module.dispose(); }); test('myAsyncMethod returns correct result', () async { final result = await module.myAsyncMethod('test'); expect(result, 'Processed: test'); }); test('handles errors gracefully', () async { final result = await module.complexMethod(MyOptionsType( someField: 'invalid', )); expect(result.success, 'false'); expect(result.error, isNotNull); }); }); }
Troubleshooting
Issue: Bindings file not found
Error: Error: Could not find 'my_plugin_module_bindings_generated.dart'
Solution:
- Make sure you've run the CLI code generation
- Check that
.module.d.tsfile exists in the same directory - Verify the module interface is properly named (
WebF{ModuleName}) - Run
webf module-codegenagain
Issue: Module not found in JavaScript
Error: Module 'MyPlugin' not found
Solution:
- Check that the Flutter package is in
pubspec.yaml - Verify the module is registered with
WebF.defineModule()in main.dart - Ensure module name matches exactly (case-sensitive)
- Run
flutter pub getand rebuild the app
Issue: Method not working
Cause: Method name mismatch or incorrect parameters
Solution:
- Check method name matches between TypeScript and Dart
- Verify parameter types match
- Check async vs sync (Promise vs direct return)
- Look at console errors for details
Issue: TypeScript types not working
Cause: npm package not generated correctly
Solution:
▼bash复制代码# Regenerate with CLI webf module-codegen output-dir \ --flutter-package-src=./my_package \ --module-name=MyModule # Check package.json exports cd output-dir cat package.json # Should have "types": "./dist/index.d.ts"
Real-World Example: Share Plugin
See the complete implementation in the WebF repository at native_plugins/share for:
- Module implementation (
share_module.dart) - TypeScript definitions (
share.module.d.ts) - Error handling and platform-specific code
- Binary data handling
- Result types with detailed information
Resources
- CLI Development Guide: cli/CLAUDE.md
- Module System Docs: webf/lib/src/module/
- Example Plugin: native_plugins/share
- WebF Architecture: docs/ARCHITECTURE.md
- Official Documentation: https://openwebf.com/en/docs/developer-guide/native-plugins
Related Skills
- Using Plugins: See
webf-native-pluginsskill for how to use existing plugins - Native UI Development: See
webf-native-ui-devskill for creating UI components - CLI Usage: See CLI documentation for code generation details
Summary
Creating Plugins
- ✅ Native plugins expose Flutter/platform capabilities as JavaScript APIs
- ✅ Different from Native UI (functional vs visual)
- ✅ Write Dart Module class extending generated bindings
- ✅ Write TypeScript definitions (.d.ts) for each module
- ✅ Use WebF CLI (
webf module-codegen) to generate npm packages and Dart bindings - ✅ Test in both Flutter and JavaScript environments
- ✅ Publish to pub.dev (Flutter) and npm (JavaScript)
Installing and Using Plugins
- ✅ Custom plugins are installed exactly like official plugins
- ✅ Requires TWO installations: Flutter package + npm package
- ✅ Add to
pubspec.yamland runflutter pub get - ✅ Register with
WebF.defineModule()in Flutter app's main.dart - ✅ Install npm package:
npm install @openwebf/webf-my-plugin - ✅ Import and use in JavaScript:
import { WebFMyPlugin } from '@openwebf/webf-my-plugin' - ✅ Always check availability:
if (typeof WebFMyPlugin !== 'undefined') - ✅ Supports public (pub.dev/npm), private registries, and local paths
Best Practices
- ✅ Follow the Share plugin example at
native_plugins/share - ✅ Return structured results (never throw to JavaScript)
- ✅ Use TypeScript for type safety
- ✅ Handle errors gracefully with success/error flags
- ✅ Document thoroughly with JSDoc comments









