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

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:

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
```
string
```
for 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.ts
```
file
✅ Generates Dart binding classes (
```
*_bindings_generated.dart
```
)
✅ Creates npm package with TypeScript types
✅ Generates JavaScript wrapper that calls
```
webf.invokeModuleAsync
```
✅ Creates
```
package.json
```
with correct metadata
✅ 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:

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}

@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.ts
```
file exists in the same directory
Verify the module interface is properly named (
```
WebF{ModuleName}
```
)
Run
```
webf module-codegen
```
again

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 get
```
and 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-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

webf-native-plugin-dev

NPX Install

Tags

SKILL.md Content

WebF Native Plugin Development

What is Native Plugin Development?

Difference: Native Plugins vs Native UI

When to Create a Native Plugin

Decision Workflow

Use Cases:

Don't Create a Native Plugin When:

Architecture Overview

Development Workflow

Overview

Step-by-Step Guide

Step 1: Create Flutter Package Structure

Step 2: Write the Module Class

Step 3: Write TypeScript Definitions

Step 4: Create Main Export File

Step 5: Generate npm Package

Step 6: Test Your Plugin

Test in Flutter App

Test in JavaScript/TypeScript

Step 7: Publish Your Plugin

Publish Flutter Package

Publish npm Package

Installing and Using Your Custom Plugin

Installation Process (Same as Official Plugins)

Step 1: Install Flutter Package

Step 2: Register the Plugin Module

Step 3: Install npm Package

Usage in JavaScript/TypeScript

Option 1: Using the npm Package (Recommended)

Option 2: Direct Module Invocation (Legacy)

Feature Detection

Error Handling

Development Workflow

During Plugin Development

After Publishing

Distribution Options

Public Distribution

Private Distribution

Local Development

Complete Installation Example

Common Plugin Patterns

1. Wrapping Existing Flutter Packages

2. Handling Binary Data

3. Event Streams

4. Permission Handling

5. Platform-Specific Implementation

Advanced Patterns

1. Error Handling and Validation

2. Resource Management

3. Batching Operations

CLI Command Reference

Basic Generation

Auto-Publishing

Best Practices

1. Naming Conventions

2. Error Handling

3. Documentation

4. Type Safety

5. Testing

Troubleshooting

Issue: Bindings file not found

Issue: Module not found in JavaScript

Issue: Method not working

Issue: TypeScript types not working

Real-World Example: Share Plugin

Resources

Related Skills

Summary

Creating Plugins

Installing and Using Plugins

Best Practices