Fix for those guys who suffered from Unkown control: .... while trying to build their own user extension⚡

[pro-grammer-SD]

Flet User Extension: Quick Start Guide

Works on any version at the times of writing the latest stable release is 0.28.3

This guide helps you build and run a Flet user extension from scratch.

1. Set Up the Folder Structure

Create a new folder named:

flet-your-extension-name

Then navigate into it:

cd flet-your-extension-name

2. Create the Extension Template

Run the following command to scaffold the extension:

flet create --template extension --project-name flet-your-extension-name

3. Install the Extension Locally

Install the extension in editable mode:

pip3.13 install -e .

4. Prepare the Example App

Change into the examples folder:

cd examples/flet_your_extension_name_example

Edit pyproject.toml if needed:

• Convert any backslashes (\) to forward slashes (/) in:

  • [tool.flet.dev_packages]
  • [tool.uv.sources]

5. Build the App

From within the examples/flet_your_extension_name_example directory, run:

flet build windows -vv

Replace windows with your target platform (e.g., macos, linux).

Important Notes:

• Make sure all components of the Visual Studio C++ workload are installed.
• Keep your path lengths short. Windows can throw errors with long paths during build.

6. Confirm Extension Registration

During build, check logs for:

Register flutter user extensions ✅

This confirms your extension was detected and registered properly.

7. Run the Example App

Navigate to the build output directory:

cd build/windows

Run your app:

flet_your_extension_name_example.exe

You should now see your custom extension rendered — for example:

My new FletYourExtensionName Flet Control

inside a purple box. If so, you're all set.

You can also run the app using flet-cli from the examples/flet_your_extension_name/ directory. This works and does not throw any errors anymore such as Unkown control: flet_your_extension_name.
The command is:

flet run

I have seen that the common issue is to build from the examples/flet_your_extension_name/src directory which is a big RED flag as it will not fetch extension details from pyproject.toml and will not work as the pyproject.toml file is in examples/flet_your_extension_name/

[usermicrodevices]

is these way to check correct build and installed custom (non Python) extension from code of running application?
we have some useful functions in flet/utils/pip.py: install_flet_package(name), ensure_flet_desktop_package_installed(), ensure_flet_web_package_installed(), ensure_flet_cli_package_installed(). also it was cool have something like ensure_custom_package_installed(name_package). maybe there is something ready here, if someone knows please tell me