Description of the Issue
The Avalonia XAML Previewer documentation currently lacks clear coverage of a critical technical prerequisite: the previewer requires a desktop windowing environment (and a desktop host project) to function.
Currently, this requirement is only mentioned inside the "Embedding Avalonia in Windows Forms" guide. Because it is omitted from the primary XAML Previewer and Live Preview documentation pages, developers frequently attempt to use the previewer inside pure cross-platform class libraries or non-desktop targets, resulting in the previewer failing to load or render entirely.
Expected Behavior
The main XAML Previewer documentation should explicitly state that a standalone Avalonia desktop application project (providing the necessary windowing and rendering infrastructure) must host or be referenced by the UI components for the previewer to work.
Actual Behavior
The requirement is missing outside of specialized embedding guides. This leads to confusing "blank screen" or "failed to load" states for developers working on non-desktop or pure library projects, causing them to waste time troubleshooting or assume the tool is broken.
Proposed Solution / Documentation Changes
Add a prominent note or "Prerequisites" section to the main Avalonia XAML Previewer and Live Preview documentation pages.
Example:
Important Note: The Avalonia XAML Previewer requires a native desktop application host to render your UI. If your XAML files reside in a cross-platform class library or a non-desktop project target, they must be linked to or hosted by a standalone Avalonia desktop application project for the previewer to function correctly.
Description of the Issue
The Avalonia XAML Previewer documentation currently lacks clear coverage of a critical technical prerequisite: the previewer requires a desktop windowing environment (and a desktop host project) to function.
Currently, this requirement is only mentioned inside the "Embedding Avalonia in Windows Forms" guide. Because it is omitted from the primary XAML Previewer and Live Preview documentation pages, developers frequently attempt to use the previewer inside pure cross-platform class libraries or non-desktop targets, resulting in the previewer failing to load or render entirely.
Expected Behavior
The main XAML Previewer documentation should explicitly state that a standalone Avalonia desktop application project (providing the necessary windowing and rendering infrastructure) must host or be referenced by the UI components for the previewer to work.
Actual Behavior
The requirement is missing outside of specialized embedding guides. This leads to confusing "blank screen" or "failed to load" states for developers working on non-desktop or pure library projects, causing them to waste time troubleshooting or assume the tool is broken.
Proposed Solution / Documentation Changes
Add a prominent note or "Prerequisites" section to the main Avalonia XAML Previewer and Live Preview documentation pages.
Example: