WebF CLI

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.

Installation

``bash
npm install -g @openwebf/webf
`

Usage

$3

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.

`bash
webf agents init [project-dir]
`

$3

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

`bash
webf codegen [output-dir] [options]
`

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

#### Options:
- --flutter-package-src : Flutter package source path containing TypeScript definitions
- --framework : Target framework - 'react' or 'vue'
- --package-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 : Custom npm registry URL (defaults to https://registry.npmjs.org/)

#### Examples:

Generate code with auto-creation of project:
`bash


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


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


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

$3

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.

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

#### Options:
- --flutter-package-src : Flutter module package path containing *.module.d.ts
- --package-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 : Custom npm registry URL (defaults to https://registry.npmjs.org/)
- --exclude : Additional glob patterns to exclude from scanning (e.g. build directories)

#### Example:

`bash


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

#### Module Events (Optional)

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

`ts
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, 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)

$3

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

`bash
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?

`

Key Features

$3

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

$3

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.

$3

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

$3

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

$3

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

$3

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

Generated Project Structure

$3

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

$3

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

$3

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

Type System

The CLI handles comprehensive type mapping between TypeScript and Dart:

$3

- 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

$3

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

$3

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

Performance Optimizations

The CLI implements several performance optimizations:

$3

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

$3

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

Development

$3

- Node.js >= 14
- npm or yarn

$3

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

$3

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

$3

`bash

Make changes to source files

npm run build # Compile TypeScript
npm test # Run tests
npm link # Link for local testing
`

Troubleshooting

$3

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

License

ISC