Dark Mode

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Add documentation to AIP-68 dev tools #53643

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking "Sign up for GitHub", you agree to our terms of service and privacy statement. We'll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Merged

Add documentation to AIP-68 dev tools #53643

Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 149 additions & 1 deletion airflow-core/docs/howto/custom-view-plugin.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,152 @@ 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 `.

Developing React Applications with the Bootstrap Tool
=====================================================

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.

Creating a New React Plugin Project
-----------------------------------

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.

React Development Workflow
---------------------------

Once your project is generated, refer to the ``README.md`` file in your project directory for complete development instructions, including:

- Available development scripts (``pnpm dev``, ``pnpm build``, etc.)
- Project structure explanation
- Development workflow with hot reload
- Building for production
- Troubleshooting common React development issues

The generated project is pre-configured with all necessary tools and follows Airflow's UI development patterns.

Integrating with Airflow
-------------------------

To integrate your React application with Airflow, you need to:

1. **Serve the built assets** you can do that on your own infrastructure or directly within Airflow using ``fastapi_apps``
2. **Register the React app** using ``react_apps`` plugin configuration

Example Plugin Implementation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create an Airflow plugin that serves your React application:

.. code-block:: python

from pathlib import Path
from fastapi import FastAPI
from starlette.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": "http://localhost:28080/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 ` 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
=============================

Expand All @@ -61,7 +207,9 @@ Adding Rest endpoints through the blueprints is still supported, those endpoints
be integrated in the FastAPI application via the WSGI Middleware and accessible
under ``/pluginsv2``.

It is not possible to extend the core UI, for instance by extending the base template, nonetheless extra menu items
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.

Expand Down
1 change: 1 addition & 0 deletions docs/spelling_wordlist.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1982,6 +1982,7 @@ views
virtualenv
virtualenvs
virtualized
Vite
vm
VolumeKmsKeyId
VolumeMount
Expand Down