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 <br...@astronomer.io> 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.