diff options
| author | Fabian Mastenbroek <mail.fabianm@gmail.com> | 2022-10-27 17:15:55 +0200 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-10-27 17:15:55 +0200 |
| commit | c4cfb6f6e0507f335fd88935857f20e88c34abd0 (patch) | |
| tree | 8dad74b6a213bb294dbcea33ebab34a3be193e77 /opendc-web/opendc-web-ui/README.md | |
| parent | fa7fdbb0126ea465130961dc37c4ef2d6feb36e9 (diff) | |
| parent | 5a3d5148a9d52487f102e52bd079006c916075c9 (diff) | |
merge: Update to Next.js 13 and React 18
This pull request updates the web interface to make use of Next.js 13 and React 18.
## Implementation Notes :hammer_and_pick:
* Drop dependency on FontAwesome
* Update to Next 13 and React 18
* Drop dependency on Roboto font
* Make root redirect non-permanent
* Do not optimize images for export
* Update to Node 18 for the build process
* Ensure consistency of build tasks
* Update README.md of web UI
* Default to anonymous auth domain
* Disable configuration of basePath
## External Dependencies :four_leaf_clover:
* Next.js 13
* React 18
* PatternFly 4
* Node 18
## Breaking API Changes :warning:
* The base path of the web UI cannot be configured anymore via the Quarkus extension.
The previous implementation relied on Next.js internals and this functionality cannot be
provided without resorting to hacks. Since this functionality was not actually used, we have
removed it for now.
Diffstat (limited to 'opendc-web/opendc-web-ui/README.md')
| -rw-r--r-- | opendc-web/opendc-web-ui/README.md | 140 |
1 files changed, 64 insertions, 76 deletions
diff --git a/opendc-web/opendc-web-ui/README.md b/opendc-web/opendc-web-ui/README.md index d562f2a4..a1133475 100644 --- a/opendc-web/opendc-web-ui/README.md +++ b/opendc-web/opendc-web-ui/README.md @@ -1,61 +1,8 @@ -<h1 align="center"> - <img src="../../docs/images/logo.png" width="100" alt="OpenDC"> - <br> - OpenDC Frontend -</h1> -<p align="center"> - Collaborative Datacenter Simulation and Exploration for Everybody -</p> +# OpenDC Web UI The user-facing component of the OpenDC stack, allowing users to build and interact with their own (virtual) datacenters. Built in *React.js* and *Redux*, with the help of [Next.js](https://nextjs.org/). -## Get Up and Running - -Looking for the full OpenDC stack? Check out the [deployment guide](../../docs/deploy.md) for instructions on -how to set up a Docker container with all of OpenDC, without the hassle of running each of the components manually. - -### Installation - -To get started, you'll need the [Node.js environment](https://nodejs.org) and -the [Yarn package manager](https://yarnpkg.com). Once you have those installed, run the following command from the root -directory of this repo: - -```bash -yarn -``` - -### Running the development server - -First, you need to set up an [Auth0](https://auth0.com) application. Check -the [documentation in the deployment guide](../../docs/deploy.md) if you're not sure how to do this. Once you have such -an ID, you need to set it as environment variable `NEXT_PUBLIC_AUTH0_CLIENT_ID` and `NEXT_PUBLIC_AUTH0_DOMAIN` -One way of doing this is to create an `.env.local` file with content `NEXT_PUBLIC_AUTH0_CLIENT_ID=YOUR_ID` and -`NEXT_PUBLIC_AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN` in the root directory of this repo. - -Once you've set this variable, start the OpenDC `docker-compose` setup. See the root README for instructions on this. - -Now, you're ready to start the development server: - -```bash -yarn dev -``` - -This will start a development server running on [`localhost:3000`](http://localhost:3000), watching for changes you make -to the code and rebuilding automatically when you save changes. - -To compile everything for camera-ready deployment, use the following command: - -```bash -yarn build -``` - -You can run the production server using Next.js as follows: - -```bash -yarn start -``` - ## Architecture The codebase follows a standard React.js structure, with static assets being contained in the `public` folder, while @@ -67,41 +14,66 @@ All pages are represented by a component in the `src/pages` directory, following the [Next.js conventions](https://nextjs.org/docs/routing/introduction) for routing. There are components for the following pages: -**index.js** - Entry page (`/`) - -**projects/index.js** - Overview of projects of the user (`/projects`) - -**projects/[project]/index.js** - Main application, with datacenter construction and simulation UI (`/projects/:projectId` +1. **index.js** - Entry page (`/`) +2. **projects/index.js** - Overview of projects of the user (`/projects`) +3. **projects/[project]/index.js** - Main application, with datacenter construction and simulation UI (`/projects/:projectId` and `/projects/:projectId/portfolios/:portfolioId`) - -**profile.js** - Profile of the current user (`/profile`) - -**404.js** - 404 page to appear when the route is invalid (`/*`) +4. **profile.js** - Profile of the current user (`/profile`) +5. **404.js** - 404 page to appear when the route is invalid (`/*`) ### Components & Containers -The building blocks of the UI are divided into so-called *components* and * -containers* ([as encouraged](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0) by the author of -Redux). *Components* are considered 'pure', rendered as a function of input properties. *Containers*, on the other hand, +The building blocks of the UI are divided into so-called *components* and *containers* +([as encouraged](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0) by the author of Redux). +*Components* are considered 'pure', rendered as a function of input properties. *Containers*, on the other hand, are wrappers around *components*, injecting state through the properties of the components they wrap. Even the canvas (the main component of the app) is built using React components, with the help of the `react-konva` module. To illustrate: A rectangular object on the canvas is defined in a way that is not very different from how we -define a standard `div` element on the splashpage. +define a standard `div` element on the splash page. + +### API Interaction + +The web-app needs to pull data in from the API of a backend running on a server. The functions that call routes are +located in `src/api`. The actual logic responsible for calling these functions is contained in `src/data`. ### State Management -Almost all state is kept in a central Redux store. State is kept there in an immutable form, only to be modified through +State for the topology editor is managed via a Redux store. State is kept there in an immutable form, only to be modified through actions being dispatched. These actions are contained in the `src/actions` folder, and the reducers (managing how state is updated according to dispatched actions) are located in `src/reducers`. If you're not familiar with the Redux approach to state management, have a look at their [official documentation](https://redux.js.org/). -### API Interaction +## Running the development server -The web-app needs to pull data in from the API of a backend running on a server. The functions that call routes are -located in `src/api`. The actual logic responsible for calling these functions is contained in `src/sagas`. These API -fetch procedures are written with the help of `redux-saga`. The [official documentation](https://redux-saga.js.org/) -of `redux-saga` can be a helpful aid in understanding that part of the codebase. +Before we can start the development server, create a file called `.env` in this directory and specify the base URL of +the API that the React frontend will communicate with. For instance, if you run the OpenDC development server: + +``` +NEXT_PUBLIC_API_BASE_URL=http://localhost:8080/api +``` + +Now, you're ready to start the Next.js development server. Run the following command in the root of the repository +(that is, two levels up where the `gradlew` file is located): + +```bash +./gradlew :opendc-web:opendc-web-ui:nextDev +``` + +This will start a development server running on [`localhost:3000`](http://localhost:3000), watching for changes you make +to the code and rebuilding automatically when you save changes. + +To compile everything for camera-ready deployment, use the following command: + +```bash +./gradlew :opendc-web:opendc-web-ui:build +``` + +You can then run the production server using Next.js as follows: + +```bash +./gradlew :opendc-web:opendc-web-ui:nextStart +``` ## Tests @@ -110,9 +82,25 @@ code they are testing, to make discovery easier. ### Running all tests -The following command runs all tests in the codebase. On top of this, it also watches the code for changes and reruns -the tests whenever any file is saved. +The following command runs all tests in the codebase using [Jest](https://jest.io). On top of this, it also watches the +code for changes and reruns the tests whenever any file is saved. + +```bash +./gradlew :opendc-web:opendc-web-ui:test +``` + +## Code Quality + +We use [Prettier](https://prettier.io) to ensure the formatting of the JavaScript codebase remains consistent. To format +the files of the codebase according to the preferred coding style, run the following command: + +```bash +./gradlew :opendc-web:opendc-web-ui:prettierFormat +``` + +Furthermore, we also employ [ESLint](https://eslint.org/) (via Next) to detect issues and problematic code in our +codebase. To check for potential issues, run the following command: ```bash -yarn test +./gradlew :opendc-web:opendc-web-ui:nextLint ``` |
