A powerful code generation tool for WebF that creates type-safe bindings between Flutter/Dart and JavaScript frameworks (React, Vue). It analyzes TypeScript definition files and generates corresponding Dart classes and JavaScript/TypeScript components.

npm install -g @openwebf/webf

The webf agents init command injects WebF Claude Code skills (from @openwebf/claude-code-skills) into your project and updates CLAUDE.md to reference them.

webf agents init [project-dir]

The webf codegen command generates Dart abstract classes and React/Vue components from TypeScript definitions. It automatically creates a project if needed.

webf codegen [output-dir] [options]

• output-dir: Path to output generated files (default: ".")

• --flutter-package-src <path>: Flutter package source path containing TypeScript definitions
• --framework <framework>: Target framework - 'react' or 'vue'
• --package-name <name>: Package name for the webf typings
• --dart-only: Only generate Dart bindings in the Flutter package (skip React/Vue code and npm package generation)
• --publish-to-npm: Automatically publish the generated package to npm
• --npm-registry <url>: Custom npm registry URL (defaults to https://registry.npmjs.org/)

Generate code with auto-creation of project:

# Generate React components from Flutter package
webf codegen my-typings --flutter-package-src=../webf_cupertino_ui --framework=react

# Generate Vue components with custom package name
webf codegen my-vue-app --flutter-package-src=./flutter_pkg --framework=vue --package-name=@myorg/webf-vue

# Use temporary directory (auto-created)
webf codegen --flutter-package-src=../webf_cupertino_ui

# Generate only Dart bindings inside the Flutter package
webf codegen --flutter-package-src=../webf_cupertino_ui --dart-only

Create a new project without code generation:

# Create React project structure
webf codegen my-project --framework=react --package-name=my-webf-react

# Create Vue project structure  
webf codegen my-project --framework=vue --package-name=my-webf-vue

Generate and publish to npm:

# Publish to default npm registry
webf codegen my-typings --flutter-package-src=../webf_ui --publish-to-npm

# Publish to custom registry
webf codegen my-typings --flutter-package-src=../webf_ui --publish-to-npm --npm-registry=https://custom.registry.com/

The webf module-codegen command generates a typed npm package and Dart bindings for a WebF module based on a TypeScript interface file (*.module.d.ts) in your Flutter package.

webf module-codegen [output-dir] [options]

• --flutter-package-src <path>: Flutter module package path containing *.module.d.ts
• --package-name <name>: NPM package name for the module (defaults to a name derived from pubspec.yaml)
• --publish-to-npm: Automatically publish the generated package to npm
• --npm-registry <url>: Custom npm registry URL (defaults to https://registry.npmjs.org/)
• --exclude <patterns...>: Additional glob patterns to exclude from scanning (e.g. build directories)

# From the CLI repo root
webf module-codegen ../packages/webf-share --flutter-package-src=../webf_modules/share --package-name=@openwebf/webf-share

This will:

• Scaffold an npm package at ../packages/webf-share
• Read *.module.d.ts from ../webf_modules/share
• Generate src/index.ts and src/types.ts that wrap webf.invokeModuleAsync('Share', ...)
• Generate Dart bindings in ../webf_modules/share/lib/src/share_module_bindings_generated.dart

If your module emits events via Dart moduleManager.emitModuleEvent(...), you can optionally declare them in the same *.module.d.ts file using:

interface WebFMyModuleModuleEvents {
  // Shorthand: only types the `event` parameter (extra defaults to `any`)
  ready: Event;

  // Tuple: [eventType, extraType] types both callback parameters
  scanResult: [Event, { deviceId: string; rssi: number }];
  click: [CustomEvent<string>, number[]];
}

When present, webf module-codegen will generate:

• WebFMyModuleModuleEventListener (typed listener with correlated event.type ↔ extra)
• WebFMyModule.addListener(eventType, listener) (returns an unsubscribe function)
• WebFMyModule.removeListener() (removes all listeners for this module)

If you don't provide all required options, the CLI will prompt you interactively:

webf codegen my-app
# CLI will ask:
# - Which framework would you like to use? (react/vue)
# - What is your package name?
# - Would you like to publish this package to npm?

The CLI automatically detects if a project needs to be created based on the presence of required files (package.json, global.d.ts, tsconfig.json).

When --flutter-package-src is not provided, the CLI searches for a Flutter package in the current directory or parent directories by looking for pubspec.yaml.

The CLI reads version and description from the Flutter package's pubspec.yaml and applies them to the generated package.json.

After code generation, the CLI automatically runs npm run build if a build script exists in the package.json.

For existing projects, the CLI can auto-detect the framework from package.json dependencies.

The CLI validates that the Flutter package has proper TypeScript configuration:

• Checks for tsconfig.json
• Verifies .d.ts files exist
• Offers to create tsconfig.json if missing

my-webf-app/
├── src/
│   ├── components/
│   │   ├── Button.tsx
│   │   ├── Input.tsx
│   │   └── ...
│   ├── utils/
│   │   └── createComponent.ts
│   └── index.ts
├── package.json
├── tsconfig.json
├── tsdown.config.ts
├── global.d.ts
└── .gitignore

my-webf-app/
├── src/
│   ├── components/
│   │   ├── Button.vue
│   │   ├── Input.vue
│   │   └── ...
│   └── index.ts
├── package.json
├── tsconfig.json
├── global.d.ts
└── .gitignore

flutter_package/
├── lib/
│   ├── src/
│   │   ├── button_bindings_generated.dart
│   │   ├── input_bindings_generated.dart
│   │   └── ...
│   └── widgets.dart
└── pubspec.yaml

The CLI handles comprehensive type mapping between TypeScript and Dart:

• string → String (Dart) / string (JS)
• number → int/double (Dart) / number (JS)
• boolean → bool (Dart) / boolean (JS)
• any → dynamic (Dart) / any (JS)
• void → void
• null → null
• undefined → handled specially

• Arrays: Type[] → List<Type> (Dart)
• Functions: Proper signature conversion
• Promises: Promise<Type> → Future<Type> (Dart)
• Union types: Handled with appropriate conversions
• Custom types: Preserved with proper imports

HTML attributes are always strings, so the generator includes automatic type conversion:

• Boolean: value == 'true' || value == ''
• Integer: int.tryParse(value) ?? 0
• Double: double.tryParse(value) ?? 0.0
• String: Direct assignment

The CLI implements several performance optimizations:

1. Source File Cache: Parsed TypeScript AST files
2. Type Conversion Cache: Frequently used type conversions
3. File Content Cache: Detect changes efficiently

Files are processed in batches for optimal performance, maximizing CPU utilization.

• Node.js >= 14
• npm or yarn

git clone https://github.com/openwebf/webf
cd webf/cli
npm install
npm run build

npm test                    # Run all tests
npm test -- --coverage      # Run with coverage
npm test -- analyzer.test   # Run specific test file

# Make changes to source files
npm run build    # Compile TypeScript
npm test         # Run tests
npm link         # Link for local testing

Missing TypeScript definitions:

• Ensure your Flutter package has .d.ts files in the lib/ directory
• Create a tsconfig.json in your Flutter package root

Build failures:

• Check that all dependencies are installed: npm install
• Verify TypeScript compilation: npm run build

Publishing errors:

• Ensure you're logged in to npm: npm login
• Verify package name availability
• Check registry URL if using custom registry

ISC