webf-native-plugin-dev by openwebf

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

```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:**
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:**
```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](https://github.com/openwebf/webf/tree/main/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](https://github.com/openwebf/webf/blob/main/cli/CLAUDE.md)
- **Module System Docs**: [webf/lib/src/module/](https://github.com/openwebf/webf/tree/main/webf/lib/src/module/)
- **Example Plugin**: [native_plugins/share](https://github.com/openwebf/webf/tree/main/native_plugins/share)
- **WebF Architecture**: [docs/ARCHITECTURE.md](https://github.com/openwebf/webf/blob/main/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