Skip to Content
DocsAdd WebF To FlutterGetting Started

Getting Started

This guide will help you install WebF and create your first WebF instance in a Flutter application.

Installation

Add webf to your pubspec.yaml:

dependencies:
  webf: ^0.23.0  # Check pub.dev for the latest version

Run:

flutter pub get

Creating Your First WebF Instance

WebF uses a managed architecture through WebFControllerManager. Here’s a minimal example:

import 'package:flutter/material.dart';
import 'package:webf/webf.dart';
 
void main() {
  // 1. Initialize the controller manager
  WebFControllerManager.instance.initialize(
    WebFControllerManagerConfig(
      maxAliveInstances: 5,
      maxAttachedInstances: 3,
    ),
  );
 
  // 2. Add a controller with content
  WebFControllerManager.instance.addWithPrerendering(
    name: 'home',
    createController: () => WebFController(),
    bundle: WebFBundle.fromUrl('https://example.com/'),
  );
 
  runApp(MyApp());
}
 
class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: WebF.fromControllerName(
          controllerName: 'home',
          loadingWidget: CircularProgressIndicator(),
        ),
      ),
    );
  }
}

This example:

  1. Initializes the controller manager with lifecycle limits
  2. Pre-renders a controller named ‘home’ with content from a URL
  3. Displays the WebF content using WebF.fromControllerName

Understanding the WebFControllerManager

The WebFControllerManager is a singleton that manages the lifecycle of all WebF instances in your app. It handles:

  • Controller Creation: Creates and initializes WebF controllers
  • Resource Management: Enforces limits on active instances
  • Lifecycle Control: Automatically attaches/detaches controllers based on visibility
  • Memory Optimization: Disposes unused controllers when limits are reached
  • State Persistence: Maintains controller state when detached

Configuration Options

WebFControllerManager.instance.initialize(
  WebFControllerManagerConfig(
    maxAliveInstances: 5,        // Max controllers in memory
    maxAttachedInstances: 3,      // Max controllers rendering simultaneously
    autoDisposeWhenLimitReached: true,  // Auto-cleanup LRU controllers
    enableDevTools: true,         // Enable Chrome DevTools debugging
    onControllerDisposed: (name, controller) {
      print('Controller $name disposed');
    },
    onControllerDetached: (name, controller) {
      print('Controller $name detached');
    },
  ),
);

Best Practices

  • Initialize in main() before runApp()
  • Set maxAliveInstances based on your app’s memory constraints
  • Keep maxAttachedInstances low (1-3) for optimal performance
  • Use lifecycle callbacks for debugging and analytics

Loading WebF Apps with WebFBundle

WebFBundle specifies where to load your WebF app from. WebF supports multiple sources:

1. Remote URL

WebFBundle.fromUrl('https://example.com/')

2. Local Assets

// First, add to pubspec.yaml:
// flutter:
//   assets:
//     - assets/web/
 
WebFBundle.fromUrl('assets:///assets/web/index.html')

3. Localhost Development

// For local development with React/Vue dev servers
WebFBundle.fromUrl('http://localhost:3000/')

4. Inline Content

WebFBundle.fromContent('''
<!DOCTYPE html>
<html>
  <body>
    <h1>Hello from WebF!</h1>
    <script>
      document.body.style.backgroundColor = 'lightblue';
    </script>
  </body>
</html>
''')

Complete Example with Pre-rendering

await WebFControllerManager.instance.addWithPrerendering(
  name: 'product_page',
  createController: () => WebFController(
    initialRoute: '/products',
  ),
  bundle: WebFBundle.fromUrl('https://myapp.com/'),
  setup: (controller) {
    // Additional setup after controller creation
    controller.onLCP = (time, isEvaluated) {
      print('LCP: $time ms');
    };
  },
);

Next Steps

Now that you have WebF installed and running, learn about:

OverviewCore Concepts