This is an automated email from the ASF dual-hosted git repository.
bbovenzi pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 5fbfe4cfd1 Update UI contributing docs (#41903)
5fbfe4cfd1 is described below
commit 5fbfe4cfd11d4cd5622011e3891eec7c7c0a63b4
Author: Brent Bovenzi <[email protected]>
AuthorDate: Wed Sep 4 10:53:39 2024 -0400
Update UI contributing docs (#41903)
* Update node_env_setup docs
* fix extra blank lines
* Address PR feedback
* Remove redundancy add a note about vite dev server
---
airflow/ui/CONTRIBUTING.md | 53 ++++---------------
contributing-docs/14_node_environment_setup.rst | 70 ++++++++++++++++++++++++-
2 files changed, 78 insertions(+), 45 deletions(-)
diff --git a/airflow/ui/CONTRIBUTING.md b/airflow/ui/CONTRIBUTING.md
index 88ee9c6fe4..73ff3ee00d 100644
--- a/airflow/ui/CONTRIBUTING.md
+++ b/airflow/ui/CONTRIBUTING.md
@@ -19,52 +19,17 @@
# Contributing to the UI
-## Getting Started
+## Quick Start
-1. Install `pnpm`. Check their [docs](https://pnpm.io/installation)
+With Breeze:
+`breeze start-airflow --dev-mode`
-2. Run `breeze start-airflow --dev-mode` will install and run the local dev
server to allow for hot-reloading during development.
+Manually:
-3. Click on the banner in the old UI to redirect you to the new ui or go to
`localhost:28080/ui`
+- Have the `dev-mode` environment variable enabled
+- Run `pnpm install && pnpm dev`
+- Note: Make sure to access the UI via the Airflow localhost port (8080 or
28080) and not the vite port (5173)
-## CLI Commands
+## More
-- `pnpm install`
-- `pnpm lint` lint check
-- `pnpm test` run ui tests
-- `pnpm build` build the project to appear in `ui/dist`, this is what the
webserver will usually look for
-- `pnpm dev` run the vite dev server to enable hot reloading for local
development. You also need the `dev_mode` environment variable enabled on the
webserver.
-
-## Learn
-
-If you're new to modern frontend development or parts of our stack, you may
want to check out these resources to understand our codebase:
-
-- Typescript is an extension of javascript to add type-checking to our app.
Files ending in `.ts` or `.tsx` will be type-checked. Check out the
[handbook](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes-func.html)
for an introduction or feel free to keep this
[cheatsheet](https://github.com/typescript-cheatsheets/react) open while
developing.
-
-- React powers our entire app so it would be valuable to learn JSX, the
html-in-js templates React utilizes. Files that contain JSX will end in `.tsx`
instead of `.ts`. Check out their official
[tutorial](https://reactjs.org/tutorial/tutorial.html#overview) for a basic
overview.
-
-- Chakra-UI is our component library and theming system. You'll notice we have
no traditional css nor html tags. This is all handled in Chakra with importing
standard components like `<Box>` or `<Text>` that are styled globally in
`src/theme.ts` file and then by passing styles as component props. Check out
their [docs](https://chakra-ui.com/docs/getting-started) to see all the
included components and hooks.
-
-- Testing is done with React Testing Library. We follow their idea of "The
more your tests resemble the way your software is used,
- the more confidence they can give you." Keep their
[cheatsheet](https://testing-library.com/docs/react-testing-library/cheatsheet)
open when writing tests
-
-- We use Vite as our app framework for running a dev server and build
commands. Check out their [docs](https://vitejs.dev/guide/) if you need to
customize it.
-
-- State management is handled with
[Context](https://reactjs.org/docs/context.html) and
[react-query](https://tanstack.com/query/latest/docs/framework/react/overview).
Context is used for App-level state that doesn't change often (authentication,
dark/light mode). React Query handles all the state and side effects (loading,
error, caching, etc) of async data from the API.
-
-## Project Structure
-
-- `/openapi` autogenerated types and queries based on the public REST API
openapi spec. Do not manually edit. To regenerate use:
-
-```console
-pnpm run codegen
-```
-
-- `/src/assets` static assets for the UI
-- `/src/components` shared components across the UI
-- `/dist` build files
-- TODO: build out project structure more
-
-## Find open issues
-
-TODO
+See [node environment setup
docs](../../contributing-docs/14_node_environment_setup.rst)
diff --git a/contributing-docs/14_node_environment_setup.rst
b/contributing-docs/14_node_environment_setup.rst
index 5d148a71a5..77ba3e9542 100644
--- a/contributing-docs/14_node_environment_setup.rst
+++ b/contributing-docs/14_node_environment_setup.rst
@@ -18,6 +18,74 @@
Node.js Environment Setup
=========================
+Contributing to the UI in Airflow
+---------------------------------
+
+In Airflow 3, we are moving the UI away from Flask App Builder views to a pure
React powered frontend living at ``airflow/ui``.
+During 3.0 development, we will need to run both the new and legacy UIs at the
same time until the new UI is feature-complete.
+But we want to limit modifications to the legacy ``airflow/www`` views, to
mainly three rules:
+
+1. Bug fixes to cherry pick for 2.10.x and 2.11
+2. The minimum necessary to unblock other Airflow 3.0 feature work
+3. Fixes to react views which we haven't migrated over yet, but can still be
ported over to the new UI
+
+Custom endpoints for the UI will also be moved away from
``airflow/www/views.py`` and to ``airflow/api_ui``.
+Contributions to the legacy views file will follow the same rules.
+Committers will exercise their judgement on what endpoints should exist in the
public ``airflow/api_connexion`` versus the private ``airflow/api_ui``
+
+Airflow UI
+----------
+
+``airflow/ui`` is our React frontend powered. Dependencies are managed by pnpm
and dev/build processes by `Vite <https://vitejs.dev/guide/>`__
+Make sure you are using recent versions of ``pnpm\>=9`` and ``node/>=20``.
``breeze start-airflow`` will build the UI automatically.
+Adding the ``--dev-mode`` flag will automatically run the vite dev server for
hot reloading the UI during local development.
+
+pnpm commands
+-------------
+
+Follow the `pnpm docs <https://pnpm.io/installation>`__ to install pnpm
locally and `nvm <https://github.com/nvm-sh/nvm>`__ to manage your node version.
+
+.. code-block:: bash
+
+ # install dependencies
+ pnpm install
+
+ # Run vite dev server for local development.
+ # The dev server will run on a different port than Airflow. To use the UI,
access it through wherever your Airflow webserver is running, usually 8080 or
28080.
+ # Trying to use the UI from the Vite port (5173) will lead to auth errors.
+ pnpm dev
+
+ # Generate production build files will be at airflow/ui/dist
+ pnpm build
+
+ # Format code in .ts, .tsx, .json, .css, .html files
+ pnpm format
+
+ # Check JS/TS code in .ts, .tsx, .html files and report any errors/warnings
+ pnpm lint
+
+ # Check JS/TS code in .ts, .tsx, .html files and report any
errors/warnings and fix them if possible
+ pnpm lint:fix
+
+ # Run tests for all .test.ts, test.tsx files
+ pnpm test
+
+ # Generate queries and types from the REST API OpenAPI spec
+ pnpm codegen
+
+Project Structure
+-----------------
+
+- ``/openapi`` autogenerated types and queries based on the public REST API
openapi spec. Do not manually edit.
+- ``/src/assets`` static assets for the UI
+- ``/src/components`` shared components across the UI
+- ``/dist`` build files
+
+
+
+DEPRECATED Airflow WWW
+----------------------
+
``airflow/www/`` contains all yarn-managed, front-end assets. Flask-Appbuilder
itself comes bundled with jQuery and bootstrap. While they may be phased out
over time, these packages are currently not managed with yarn.
@@ -103,7 +171,7 @@ Most IDE directly integrate with these tools, you can also
manually run them wit
yarn test
React, JSX and Chakra
------------------------------
+---------------------
In order to create a more modern UI, we have started to include `React
<https://reactjs.org/>`__ in the ``airflow/www/`` project.
If you are unfamiliar with React then it is recommended to check out their
documentation to understand components and jsx syntax.
