Overview

Flet enables publishing web applications as dynamic websites by leveraging FastAPI and ASGI-compatible web servers like Uvicorn.

Sync and Async Handlers

Flet web apps support both synchronous and asynchronous event handlers.

Synchronous handlers run in a threading.Thread, potentially leading to bottlenecks with many users.

Asynchronous handlers are recommended for I/O-bound operations and when using async-ready libraries.

Running the App Locally

Use flet run --web to launch the app in a browser.

Specify a fixed port with flet run --web --port .

Running the App in Production

Execute the app directly with python .

Uvicorn is the default ASGI server.

In headless Linux environments (Docker, EC2), the app defaults to port 8000 and does not open a browser.

Force headless behavior with FLET_FORCE_WEB_SERVER=true environment variable.

ASGI Web Server Integration

Flet apps can be served by any ASGI-compatible server.

Export the ASGI app using ft.run(main, export_asgi_app=True).

**Hypercorn:** hypercorn main:app --bind 0.0.0.0:

**Daphne:** daphne -b 0.0.0.0 -p main:app

**Gunicorn:** gunicorn --bind 0.0.0.0: -k uvicorn.workers.UvicornWorker main:app

Assets

Web app resources (index.html, Flutter engine, favicon, etc.) are bundled with flet.

Customize assets by specifying assets_dir in ft.run() or via FLET_ASSETS_DIR environment variable.

Default assets_dir is assets.

**Customization:**

- favicon.png: Replaces the default favicon (min 32x32 PNG). - icons/loading-animation.png: Replaces the default loading animation. - manifest.json: Configures PWA details (name, short_name, description, theme_color, background_color). - Icons (icon-192.png, icon-512.png, icon-maskable-192.png, icon-maskable-512.png, apple-touch-icon-192.png): Placed in assets/icons for PWA display.

Environment Variables

FLET_FORCE_WEB_SERVER: true to force web server mode.

FLET_SERVER_PORT: Port for the web app (defaults to 8000 on Linux/forced web server, else random).

FLET_SERVER_IP: IP address to bind to (defaults to 0.0.0.0).

FLET_ASSETS_DIR: Absolute path to assets directory.

FLET_UPLOAD_DIR: Absolute path for uploaded files.

FLET_MAX_UPLOAD_SIZE: Max upload size in bytes.

FLET_SECRET_KEY: Secret key for signing upload URLs.

FLET_WEB_APP_PATH: URL path for the web app (defaults to /).

FLET_SESSION_TIMEOUT: Session lifetime in seconds (defaults to 3600).

FLET_OAUTH_STATE_TIMEOUT: OAuth state lifetime in seconds (defaults to 600).

FLET_WEB_RENDERER: Flutter rendering mode (canvaskit, html, auto).

FLET_WEB_USE_COLOR_EMOJI: true to load font with color emojis.

FLET_WEB_ROUTE_URL_STRATEGY: Routing strategy (path or hash).

FLET_WEBSOCKET_HANDLER_ENDPOINT: WebSocket endpoint path (defaults to /ws).

FLET_UPLOAD_HANDLER_ENDPOINT: Upload endpoint path (defaults to /upload).

FLET_OAUTH_CALLBACK_HANDLER_ENDPOINT: OAuth callback endpoint path (defaults to /oauth_callback).

Advanced FastAPI Scenarios

Flet FastAPI App (flet.fastapi.app)

Creates a FastAPI app handling Flet sessions.

Mounts endpoints: /ws (WebSocket), /upload (PUT), /oauth_callback (GET), / (static files/SPA).

**Parameters:** session_handler, assets_dir, app_name, app_short_name, app_description, web_renderer, use_color_emoji, route_url_strategy, upload_dir, max_upload_size, secret_key, session_timeout_seconds, oauth_state_timeout_seconds.

Hosting Multiple Flet Apps

Use app.mount() to attach multiple Flet apps to different URL paths.

Mount sub-apps before the root app.

Example: app.mount("/sub-app", flet_fastapi.app(sub_main)).

Adding Flet to Existing FastAPI App

Use flet.fastapi.app_manager.start() and flet.fastapi.app_manager.shutdown() within the FastAPI app's lifespan or events.

Mount the Flet app using app.mount("/flet-app", flet_fastapi.app(main)).

Configuring Individual Endpoints

#### Static Files (FletStaticFiles)

Serves Flet app static files and user assets.

**Parameters:** app_mount_path, assets_dir, app_name, app_short_name, app_description, web_renderer, use_color_emoji, route_url_strategy, websocket_endpoint_path.

#### WebSocket Handler (FletApp)

Handles WebSocket connections for real-time updates.

Use @app.websocket("/path/ws") and FletApp(session_handler).handle(websocket).

**Parameters:** session_handler, session_timeout_seconds, oauth_state_timeout_seconds, upload_endpoint_path, secret_key.

#### Uploads Handler (FletUpload)

Handles file uploads from FilePicker.

Use @app.put("/upload") and FletUpload(upload_dir).handle(request).

#### OAuth Callback Handler (FletOAuth)

Handles OAuth flow callback requests.

Use @app.get("/oauth_callback") and FletOAuth().handle(request).