airflow-core/docs/howto/custom-view-plugin.rst
.. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
.. http://www.apache.org/licenses/LICENSE-2.0
.. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Airflow has feature that allows to integrate a custom UI along with its core UI using the Plugin manager.
Plugins integrate with the Airflow core RestAPI. In this plugin,
three object references are derived from the base class airflow.plugins_manager.AirflowPlugin.
They are fastapi_apps, fastapi_root_middlewares, external_views and react_apps.
Using fastapi_apps in Airflow plugin, the core RestAPI can be extended to support extra endpoints to serve custom static file or any other json/application responses. In this object reference, the list of dictionaries with FastAPI application and metadata information like the name and the url prefix are passed on.
Using fastapi_root_middlewares in Airflow plugin, allows to register custom middleware at the root of the FastAPI application. This middleware can be used to add custom headers, logging, or any other functionality to the entire FastAPI application, including core endpoints. In this object reference, the list of dictionaries with Middleware factories object, initialization parameters and some metadata information like the name are passed on.
Using external_views in Airflow plugin, allows to register custom views that are rendered in iframes or external link in the Airflow UI. This is useful for integrating external applications or custom dashboards into the Airflow UI. In this object reference, the list of dictionaries with the view name, href (templatable), destination and optional parameters like the icon and url_route are passed on.
Using react_apps in Airflow plugin, allows to register custom React applications that can be rendered in the Airflow UI. This is useful for integrating custom React components or applications into the Airflow UI. In this object reference, the list of dictionaries with the app name, bundle_url (where to load the js assets, templatable), destination and optional parameters like the icon and url_route are passed on.
Information and code samples to register fastapi_apps, fastapi_root_middlewares, external_views and react_apps are
available in :doc:plugin </administration-and-deployment/plugins>.
.. warning:: React applications are new in Airflow 3.1 and should be considered experimental. The feature may be subject to changes in future versions without warning based on user feedback and errors reported. Dependency and state interactions between the UI and plugins may need to be refactored, which will also change the bootstrapped example project provided.
|experimental|
Airflow provides a React plugin bootstrap tool to help developers quickly create, develop, and integrate external React applications into the core UI. This is the most flexible and recommended way to customize the Airflow UI. This tool generates a complete React project structure that builds as a library compatible with dynamic imports and shares React instances with the host Airflow application.
The bootstrap tool is located in dev/react-plugin-tools/ and provides a simple CLI to generate new React plugin projects:
.. code-block:: bash
# Navigate to the bootstrap tool directory
cd dev/react-plugin-tools
# Create a new plugin project
python bootstrap.py my-awesome-plugin
# Or specify a custom directory
python bootstrap.py my-awesome-plugin --dir /path/to/my-projects/my-awesome-plugin
This generates a complete React project with Vite, TypeScript, Chakra UI integration, and proper configuration for building as a library that integrates with Airflow's UI.
.. warning:: It is highly recommended to use the bootstrap tool to create a new React Plugin project. There are specific bundling configurations required to ensure compatibility with Airflow's Core UI and manually setting up a project may lead to integration issues. If you already have an existing React project that you want to integrate, you can take a look at the bootstrap tool code and the generated build configuration files for reference. React and React-DOM are shared dependencies with the host application and need to have compatible versions.
Once your project is generated, refer to the README.md file in your project directory for complete development instructions, including:
pnpm dev, pnpm build, etc.)The generated project is pre-configured with all necessary tools and follows Airflow's UI development patterns.
To integrate your React application with Airflow, you need to:
fastapi_appsreact_apps plugin configurationExample Plugin Implementation
Create an Airflow plugin that serves your React application:
.. code-block:: python
from pathlib import Path
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
import mimetypes
from airflow.plugins_manager import AirflowPlugin
# Ensure proper MIME types for cjs files
mimetypes.add_type("application/javascript", ".cjs")
# Create FastAPI app to serve static files
app = FastAPI()
# Mount your React app's dist folder
react_app_directory = Path(__file__).parent.joinpath("my-awesome-plugin", "dist")
app.mount(
"/my-react-app",
StaticFiles(directory=react_app_directory, html=True),
name="my_react_app_static",
)
class MyReactPlugin(AirflowPlugin):
name = "My React Plugin"
# Serve static files
fastapi_apps = [
{
"app": app,
"url_prefix": "/my-plugin",
"name": "My Plugin Static Server",
}
]
# Register React application
react_apps = [
{
"name": "My Awesome React App",
"url_route": "my-awesome-app",
"bundle_url": "https://airflow-domain/my-plugin/my-react-app/main.umd.cjs",
"destination": "nav",
}
]
Plugin Configuration Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
React apps support several configuration options, you can take a look at :doc:`plugin </administration-and-deployment/plugins>` for more details.
Integration Best Practices
---------------------------
The generated template follows these best practices for Airflow integration:
1. **External Dependencies**: React and common libraries are marked as external to avoid conflicts with the host application
2. **Global Naming**: Uses standardized global name (``AirflowPlugin``) for consistency
3. **Library Build**: Configured as UMD library with proper externalization for dynamic imports
4. **MIME Types**: Proper JavaScript MIME type handling for ``.cjs`` files because FastAPI serves them as plain text by default
Deployment Strategies
---------------------
External Hosting
~~~~~~~~~~~~~~~~
You can also host assets on external infrastructure:
.. code-block:: python
react_apps = [
{
"name": "My External App",
"url_route": "my-external-app",
"bundle_url": "https://my-cdn.com/main.umd.cjs",
"destination": "nav",
}
]
Troubleshooting Integration Issues
-----------------------------------
Common integration issues and solutions:
**MIME type issues**
Ensure ``.js`` and ``.cjs`` files are served with correct MIME type using ``mimetypes.add_type("application/javascript", ".cjs")``.
**Component not loading**
Check that the bundle URL is accessible and matches the expected format.
**React development issues**
Refer to the ``README.md`` file generated with your project for detailed troubleshooting of React-specific development issues.
Support for Airflow 2 plugins
=============================
Airflow 2 plugins are still supported with some limitations. More information on such
plugins can be found in the Airflow 2 documentation.
Adding Rest endpoints through the blueprints is still supported, those endpoints will
be integrated in the FastAPI application via the WSGI Middleware and accessible
under ``/pluginsv2``.
Adding Flask-AppBuilder views ( ``appbuilder_views`` ) via the Airflow 2 is still supported in its own iframe.
It is not possible to extend the AF3 core UI, for instance by extending the base template, nonetheless extra menu items
of the auth managers are added to the core UI security tab and their ``href`` are rendered in iframes.
This is how the fab provider integrates users, roles, actions, resources and permissions custom views in the Airflow 3 UI.
Airflow 3 plugins will be improved to allow UI customization for the entire react app, it is recommended
to upgrade your plugins to Airflow 3 plugins when possible. Until then for a temporary or custom needs
it is possible to use a Middleware to inject custom javascript or css to the core UI index request.