webf-native-plugin-dev（webf 原生插件开发）

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

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-plugins skill 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-dev skill instead)
• ❌ Standard web APIs already provide the functionality
• ❌ An official plugin already exists (use webf-native-plugins skill)
• ❌ You're building a one-off feature (use direct module invocation)

Architecture Overview

A native plugin consists of three layers:

┌─────────────────────────────────────────┐
│  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

# 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:

# Create Flutter package
flutter create --template=package webf_my_plugin

cd webf_my_plugin

Directory structure:

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:

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

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

/**
 * 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 string for success/failure flags (for backward compatibility)

Step 4: Create Main Export File

lib/webf_my_plugin.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:

# 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:

1. ✅ Parses your .d.ts file
2. ✅ Generates Dart binding classes (*_bindings_generated.dart)
3. ✅ Creates npm package with TypeScript types
4. ✅ Generates JavaScript wrapper that calls webf.invokeModuleAsync
5. ✅ Creates package.json with correct metadata
6. ✅ Runs npm run build if a build script exists

Generated output structure:

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:

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:

npm install @openwebf/webf-my-plugin

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

# In Flutter package directory
flutter pub publish

# Or for private packages
flutter pub publish --server=https://your-private-registry.com

Publish npm Package

# 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:

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:

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:

flutter pub get

Step 2: Register the Plugin Module

In your Flutter app's main.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:

# 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:

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:

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:

<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:

// 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:

// 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

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

# 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

# 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:

# 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:

# 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:

dependencies:
  webf_my_plugin:
    path: ../webf_my_plugin  # Relative path

npm Package:

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):

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):

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

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

@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:

interface WebFMyPlugin {
  processImageData(imageData: ArrayBuffer | Uint8Array): Promise<boolean>;
}

3. Event Streams

For continuous data streams (sensors, location updates):

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:

// Listen for events
webf.on('SensorPlugin:data', (event) => {
  console.log('Sensor data:', event.detail);
});

await WebFSensorPlugin.startListening('accelerometer');

4. Permission Handling

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

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

@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

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

@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

# 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

# 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

// 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

/// 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

// 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

// 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:

1. Make sure you've run the CLI code generation
2. Check that .module.d.ts file exists in the same directory
3. Verify the module interface is properly named (WebF{ModuleName})
4. Run webf module-codegen again

Issue: Module not found in JavaScript

Error: Module 'MyPlugin' not found

Solution:

1. Check that the Flutter package is in pubspec.yaml
2. Verify the module is registered with WebF.defineModule() in main.dart
3. Ensure module name matches exactly (case-sensitive)
4. Run flutter pub get and rebuild the app

Issue: Method not working

Cause: Method name mismatch or incorrect parameters

Solution:

1. Check method name matches between TypeScript and Dart
2. Verify parameter types match
3. Check async vs sync (Promise vs direct return)
4. Look at console errors for details

Issue: TypeScript types not working

Cause: npm package not generated correctly

Solution:

# 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-plugins skill for how to use existing plugins
• Native UI Development: See webf-native-ui-dev skill 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.yaml and run flutter 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