2022-08-26 09:25:31 +02:00
|
|
|
# frontend
|
2021-05-07 08:31:25 +02:00
|
|
|
|
2022-08-26 09:25:31 +02:00
|
|
|
This directory contains the Unleash Admin UI frontend app.
|
2017-01-04 22:55:50 +01:00
|
|
|
|
2022-03-25 12:13:39 +01:00
|
|
|
## Run with a local instance of the unleash-api
|
2021-05-07 08:31:25 +02:00
|
|
|
|
chore: simplify package scripts (#3736)
# Simplify package scripts
This PR's purpose is to raise a discussion surrounding our current
package scripts.
It includes some suggestions that aim to simplify the scripts and
hopefully bring a much more straightforward approach to developing and
contributing to Unleash.
Building (prod) should only happen **explicitly** and when needed.
## Before PR (current behavior)
- Clone the project;
- Open 2 terminals: One for `unleash` and another for
`unleash/frontend`;
- On `unleash`:
- Run `yarn` (which will also build, for some reason?);
- Run `yarn start:dev` to start backend in dev mode (`tsc-watch`);
- On `unleash/frontend`:
- Run `yarn` (which will also build, for some reason?);
- Run `yarn start` to start frontend in dev mode (`vite`);
So it seems to me like we build unnecessarily every time we install
dependencies. Neither dev scripts need to build the project, as backend
uses `tsc-watch` and frontend uses `vite`. I'm unsure why this is the
case, as building can take a very long time.
There's also some complexity in the way we need to split the terminal to
`cd` into `frontend` and treat it as a different project. The fact that
we have different script names is also confusing (`yarn start`, `yarn
start:dev`, etc).
## After PR
- Clone the project;
- Run `yarn` to install all dependencies;
- Run `yarn dev` to get started developing Unleash;
Running `yarn` should take care of everything needed to start
developing. This includes installing dependencies for frontend as well.
It should not build projects if we are not being explicit about it,
especially since we don't need to build them at this stage.
Running `yarn dev` should start the project in dev mode. This means
running both projects in `dev` mode, which for `backend` means running
`tsc-watch` and for `frontend` means running `vite`.
Here this PR attempts to provide a better DX by using
[concurrently](https://www.npmjs.com/package/concurrently) and
[wait-on](https://www.npmjs.com/package/wait-on) - This means both tasks
are ran simultaneously, stdout is labeled accordingly, and are stopped
together. It also means that `frontend` waits for `backend` to be
serving at `4242` before starting, since `frontend` starts pretty much
immediately with `vite` and `backend` takes a bit longer. Of course,
when the `backend` is hot-reloading you may still find some
`ECONNREFUSED`s on `frontend` stdout while it recompiles.
No more splitting your terminal and treating `frontend` as a separate
project.
## Discussion points
Maybe there's a better alternative to `tsc-watch`? I briefly explored
some alternatives and while they had a much faster starting speed,
hot-reload was sometimes slower. IMO we should aspire to run
`src/server-dev.ts` directly and only compile when needed.
Running `dev:backend` still serves a version of the frontend (at 4242).
**Why? Can we remove that behavior?**
I can't imagine a scenario in dev where we wouldn't want to run the
latest version of the frontend with `vite`.
~~**Note:** This PR removes all other out-of-scope scripts to focus on
this revamp. If we decide to merge it, we should evaluate what other
existing scripts we still want to include. May be a good opportunity to
clean up unused ones and only include the ones we really use. This
includes scripts that our GH actions rely on.~~
**Update:** In an effort to minimize impact surface of this PR and make
it a bit more ready for merging:
- It updates some docs in
https://github.com/Unleash/unleash/pull/3736/commits/2a4ff805e87b65d9c1256effaa189ddcccba15fb
and
https://github.com/Unleash/unleash/pull/3736/commits/1bbc4882519b5a82e3116f0be255ad24a6f3ce53
to reflect our new simplified flow;
- It includes the old package scripts for now in
https://github.com/Unleash/unleash/pull/3736/commits/039bc04699ac880e491fd3ce01f9bcd6f97a94b9;
- It updates some of our GH actions to reflect the new scripts in
https://github.com/Unleash/unleash/pull/3736/commits/7782cb9b12e37ee844507e41ef2b7137eaf55666;
Given its current status I'll promote the PR to "ready for review".
I still think we should have a second look at our existing scripts and
GH actions to see what we really need and/or should adapt, but it should
be a team effort so we have a broader context. Maybe on a follow-up PR.
Does this require any changes to related projects (e.g. Enterprise)?
---------
Co-authored-by: Gastón Fournier <gaston@getunleash.io>
2023-05-12 12:23:22 +02:00
|
|
|
Refer to the [Contributing to Unleash](../CONTRIBUTING.md#how-to-run-the-project) guide for instructions.
|
|
|
|
|
The frontend dev server runs (in port 3000) simultaneously with the backend dev server (in port 4242):
|
2022-03-25 12:13:39 +01:00
|
|
|
|
|
|
|
|
```
|
2021-10-08 22:20:47 +02:00
|
|
|
yarn install
|
chore: simplify package scripts (#3736)
# Simplify package scripts
This PR's purpose is to raise a discussion surrounding our current
package scripts.
It includes some suggestions that aim to simplify the scripts and
hopefully bring a much more straightforward approach to developing and
contributing to Unleash.
Building (prod) should only happen **explicitly** and when needed.
## Before PR (current behavior)
- Clone the project;
- Open 2 terminals: One for `unleash` and another for
`unleash/frontend`;
- On `unleash`:
- Run `yarn` (which will also build, for some reason?);
- Run `yarn start:dev` to start backend in dev mode (`tsc-watch`);
- On `unleash/frontend`:
- Run `yarn` (which will also build, for some reason?);
- Run `yarn start` to start frontend in dev mode (`vite`);
So it seems to me like we build unnecessarily every time we install
dependencies. Neither dev scripts need to build the project, as backend
uses `tsc-watch` and frontend uses `vite`. I'm unsure why this is the
case, as building can take a very long time.
There's also some complexity in the way we need to split the terminal to
`cd` into `frontend` and treat it as a different project. The fact that
we have different script names is also confusing (`yarn start`, `yarn
start:dev`, etc).
## After PR
- Clone the project;
- Run `yarn` to install all dependencies;
- Run `yarn dev` to get started developing Unleash;
Running `yarn` should take care of everything needed to start
developing. This includes installing dependencies for frontend as well.
It should not build projects if we are not being explicit about it,
especially since we don't need to build them at this stage.
Running `yarn dev` should start the project in dev mode. This means
running both projects in `dev` mode, which for `backend` means running
`tsc-watch` and for `frontend` means running `vite`.
Here this PR attempts to provide a better DX by using
[concurrently](https://www.npmjs.com/package/concurrently) and
[wait-on](https://www.npmjs.com/package/wait-on) - This means both tasks
are ran simultaneously, stdout is labeled accordingly, and are stopped
together. It also means that `frontend` waits for `backend` to be
serving at `4242` before starting, since `frontend` starts pretty much
immediately with `vite` and `backend` takes a bit longer. Of course,
when the `backend` is hot-reloading you may still find some
`ECONNREFUSED`s on `frontend` stdout while it recompiles.
No more splitting your terminal and treating `frontend` as a separate
project.
## Discussion points
Maybe there's a better alternative to `tsc-watch`? I briefly explored
some alternatives and while they had a much faster starting speed,
hot-reload was sometimes slower. IMO we should aspire to run
`src/server-dev.ts` directly and only compile when needed.
Running `dev:backend` still serves a version of the frontend (at 4242).
**Why? Can we remove that behavior?**
I can't imagine a scenario in dev where we wouldn't want to run the
latest version of the frontend with `vite`.
~~**Note:** This PR removes all other out-of-scope scripts to focus on
this revamp. If we decide to merge it, we should evaluate what other
existing scripts we still want to include. May be a good opportunity to
clean up unused ones and only include the ones we really use. This
includes scripts that our GH actions rely on.~~
**Update:** In an effort to minimize impact surface of this PR and make
it a bit more ready for merging:
- It updates some docs in
https://github.com/Unleash/unleash/pull/3736/commits/2a4ff805e87b65d9c1256effaa189ddcccba15fb
and
https://github.com/Unleash/unleash/pull/3736/commits/1bbc4882519b5a82e3116f0be255ad24a6f3ce53
to reflect our new simplified flow;
- It includes the old package scripts for now in
https://github.com/Unleash/unleash/pull/3736/commits/039bc04699ac880e491fd3ce01f9bcd6f97a94b9;
- It updates some of our GH actions to reflect the new scripts in
https://github.com/Unleash/unleash/pull/3736/commits/7782cb9b12e37ee844507e41ef2b7137eaf55666;
Given its current status I'll promote the PR to "ready for review".
I still think we should have a second look at our existing scripts and
GH actions to see what we really need and/or should adapt, but it should
be a team effort so we have a broader context. Maybe on a follow-up PR.
Does this require any changes to related projects (e.g. Enterprise)?
---------
Co-authored-by: Gastón Fournier <gaston@getunleash.io>
2023-05-12 12:23:22 +02:00
|
|
|
yarn dev
|
2016-11-10 14:26:24 +01:00
|
|
|
```
|
|
|
|
|
|
2022-10-19 14:02:00 +02:00
|
|
|
## Run with a sandbox instance of the Unleash API
|
2022-03-25 12:13:39 +01:00
|
|
|
|
2022-10-19 14:02:00 +02:00
|
|
|
Alternatively, instead of running unleash-api on localhost, you can use a remote instance:
|
2017-01-04 22:55:50 +01:00
|
|
|
|
2022-03-25 12:13:39 +01:00
|
|
|
```
|
2023-03-15 13:17:32 +01:00
|
|
|
cd ./frontend
|
2021-10-08 22:20:47 +02:00
|
|
|
yarn install
|
2022-10-19 14:02:00 +02:00
|
|
|
yarn run start:sandbox
|
2017-01-04 22:55:50 +01:00
|
|
|
```
|
|
|
|
|
|
2022-04-26 10:53:46 +02:00
|
|
|
## Running end-to-end tests
|
2022-03-25 12:13:39 +01:00
|
|
|
|
2022-04-26 10:53:46 +02:00
|
|
|
We have a set of Cypress tests that run on the build before a PR can be merged
|
|
|
|
|
so it's important that you check these yourself before submitting a PR.
|
2022-03-25 12:13:39 +01:00
|
|
|
On the server the tests will run against the deployed Heroku app so this is what you probably want to test against:
|
|
|
|
|
|
|
|
|
|
```
|
2022-10-19 14:02:00 +02:00
|
|
|
yarn run start:sandbox
|
2022-03-25 12:13:39 +01:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
In a different shell, you can run the tests themselves:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
yarn run e2e:heroku
|
|
|
|
|
```
|
|
|
|
|
|
2022-04-26 10:53:46 +02:00
|
|
|
If you need to test against patches against a local server instance,
|
|
|
|
|
you'll need to run that, and then run the end to end tests using:
|
2021-05-07 08:31:25 +02:00
|
|
|
|
2022-03-25 12:13:39 +01:00
|
|
|
```
|
|
|
|
|
yarn run e2e
|
|
|
|
|
```
|
|
|
|
|
|
2022-04-26 10:53:46 +02:00
|
|
|
You may also need to test that a feature works against the enterprise version of unleash.
|
|
|
|
|
Assuming the Heroku instance is still running, this can be done by:
|
2019-10-05 09:55:08 +02:00
|
|
|
|
2022-03-25 12:13:39 +01:00
|
|
|
```
|
|
|
|
|
yarn run start:enterprise
|
|
|
|
|
yarn run e2e
|
|
|
|
|
```
|
2022-04-26 10:53:46 +02:00
|
|
|
|
|
|
|
|
## Generating the OpenAPI client
|
|
|
|
|
|
|
|
|
|
The frontend uses an OpenAPI client generated from the backend's OpenAPI spec.
|
|
|
|
|
Whenever there are changes to the backend API, the client should be regenerated:
|
|
|
|
|
|
2023-08-24 12:13:02 +02:00
|
|
|
For now we only use generated types (src/openapi/models).
|
|
|
|
|
We will use methods (src/openapi/apis) for new features soon.
|
|
|
|
|
|
2022-04-26 10:53:46 +02:00
|
|
|
```
|
2023-08-24 12:13:02 +02:00
|
|
|
yarn gen:api
|
|
|
|
|
rm -rf src/openapi/apis
|
2022-04-26 10:53:46 +02:00
|
|
|
```
|
|
|
|
|
|
2023-08-24 12:13:02 +02:00
|
|
|
clean up `src/openapi/index.ts` imports, only keep first line `export * from './models';`
|
|
|
|
|
|
2022-04-26 10:53:46 +02:00
|
|
|
This script assumes that you have a running instance of the enterprise backend at `http://localhost:4242`.
|
|
|
|
|
The new OpenAPI client will be generated from the runtime schema of this instance.
|
|
|
|
|
The target URL can be changed by setting the `UNLEASH_OPENAPI_URL` env var.
|
2023-01-12 11:34:45 +01:00
|
|
|
|
|
|
|
|
## Analyzing bundle size
|
|
|
|
|
|
|
|
|
|
`npx vite-bundle-visualizer` in the root of the frontend directory
|
