diff --git a/frontend/.gitignore b/frontend/.gitignore index a547bf36d8..4eb6586f19 100644 --- a/frontend/.gitignore +++ b/frontend/.gitignore @@ -11,6 +11,7 @@ node_modules dist dist-ssr *.local +openapi.json # Editor directories and files .vscode/* diff --git a/frontend/.nvmrc b/frontend/.nvmrc new file mode 100644 index 0000000000..8cbe18560a --- /dev/null +++ b/frontend/.nvmrc @@ -0,0 +1 @@ +18.x.x \ No newline at end of file diff --git a/frontend/README.md b/frontend/README.md index 21e2bf91eb..7dd453b6dc 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1,18 +1,53 @@ # FastAPI Project - Frontend +The frontend is built with [Vite](https://vitejs.dev/), [React](https://reactjs.org/), [TypeScript](https://www.typescriptlang.org/), [TanStack Query](https://tanstack.com/query), [TanStack Router](https://tanstack.com/router) and [Chakra UI](https://chakra-ui.com/). + ## Frontend development -* Enter the `frontend` directory, install the NPM packages and start the live server using the `npm` scripts: +Before you begin, ensure that you have either the Node Version Manager (nvm) or Fast Node Manager (fnm) installed on your system. + +* To install fnm follow the [official fnm guide](https://github.com/Schniz/fnm#installation). If you prefer nvm, you can install it using the [official nvm guide](https://github.com/nvm-sh/nvm#installing-and-updating). + +* After installing either nvm or fnm, proceed to the `frontend` directory: ```bash cd frontend +``` +* If the Node.js version specified in the `.nvmrc` file isn't installed on your system, you can install it using the appropriate command: + +```bash +# If using fnm +fnm install + +# If using nvm +nvm install +``` + +* Once the installation is complete, switch to the installed version: + +```bash +# If using fnm +fnm use + +# If using nvm +nvm use +``` + +* Within the `frontend` directory, install the necessary NPM packages: + +```bash npm install +``` + +* And start the live server with the following `npm` script: + +```bash npm run dev ``` -Then open your browser at http://localhost:5173/. +* Then open your browser at http://localhost:5173/. -Notice that this live server is not running inside Docker, it is for local development, and that is the recommended workflow. Once you are happy with your frontend, you can build the frontend Docker image and start it, to test it in a production-like environment. But compiling the image at every change will not be as productive as running the local development server with live reload. +Notice that this live server is not running inside Docker, it's for local development, and that is the recommended workflow. Once you are happy with your frontend, you can build the frontend Docker image and start it, to test it in a production-like environment. But building the image at every change will not be as productive as running the local development server with live reload. Check the file `package.json` to see other available options. @@ -21,7 +56,9 @@ Check the file `package.json` to see other available options. If you are developing an API-only app and want to remove the frontend, you can do it easily: * Remove the `./frontend` directory. + * In the `docker-compose.yml` file, remove the whole service / section `frontend`. + * In the `docker-compose.override.yml` file, remove the whole service / section `frontend`. Done, you have a frontend-less (api-only) app. 🤓 @@ -38,15 +75,43 @@ But it would be only to clean them up, leaving them won't really have any effect ## Generate Client * Start the Docker Compose stack. -* Download the OpenAPI JSON file from `http://localhost/api/v1/openapi.json` and copy it to a new file `openapi.json` next to the `package.json` file. -* To simplify the names in the generated frontend client code, modifying the `openapi.json` file, run: + +* Download the OpenAPI JSON file from `http://localhost/api/v1/openapi.json` and copy it to a new file `openapi.json` at the root of the `frontend` directory. + +* To simplify the names in the generated frontend client code, modify the `openapi.json` file by running the following script: ```bash node modify-openapi-operationids.js ``` -* To generate or update the frontend client, run: +* To generate the frontend client, run: ```bash npm run generate-client ``` + +* Commit the changes. + +Notice that everytime the backend changes (changing the OpenAPI schema), you should follow these steps again to update the frontend client. + +## Using a Remote API + +If you want to use a remote API, you can set the environment variable `VITE_API_URL` to the URL of the remote API. For example, you can set it in the `frontend/.env` file: + +```env +VITE_API_URL=https://my-remote-api.example.com +``` + +Then, when you run the frontend, it will use that URL as the base URL for the API. + +## Code Structure + +The frontend code is structured as follows: + +* `frontend/src` - The main frontend code. +* `frontend/src/assets` - Static assets. +* `frontend/src/client` - The generated OpenAPI client. +* `frontend/src/components` - The different components of the frontend. +* `frontend/src/hooks` - Custom hooks. +* `frontend/src/routes` - The different routes of the frontend which include the pages. +* `theme.tsx` - The Chakra UI custom theme.