232 lines
10 KiB
Markdown
232 lines
10 KiB
Markdown
# Vega front-end monorepo
|
|
|
|
The front-end monorepo provides a toolkit for building apps that interact with Vega, as well as the apps themselves.
|
|
|
|
This repository is managed using [Nx](https://nx.dev).
|
|
|
|
# 🔎 Applications in this repo
|
|
|
|
### [Block explorer](./apps/explorer)
|
|
|
|
The Vega block explorer provides an interface that allows users to search for and see transactions, blocks, parties, assets, markets and more on the Vega chain.
|
|
|
|
### [Trading UI](./apps/trading)
|
|
|
|
The trading interface built based on a component toolkit. It will provide a way for participants to interact with markets and provide resources for others to build additional open-source user interfaces.
|
|
|
|
### [Token](./apps/token)
|
|
|
|
The utility dApp for interacting with the Vega token and using its' utility. This includes; delegation, nomination, governance and redemption of tokens.
|
|
|
|
### [Explorer](./apps/explorer)
|
|
|
|
The block explorer for the Vega network, showing details of raw chain states and the state of markets on the Vega network.
|
|
|
|
### [Static](./apps/static)
|
|
|
|
Hosting for static content being shared across apps, for example fonts.
|
|
|
|
### [Multisig-signer](./apps/multisig-signer)
|
|
|
|
The utility dApp for validators wishing to add or remove themselves as a signer of the multisig contract.
|
|
|
|
# 🧱 Libraries in this repo
|
|
|
|
### [UI toolkit](./libs/ui-toolkit)
|
|
|
|
The UI toolkit contains a set of components used to build interfaces that can interact with the Vega protocol, and follow the design style of the project.
|
|
It contains a storybook that can be served with `yarn nx run ui-toolkit:storybook`.
|
|
|
|
### [Tailwind CSS config](./libs/tailwindcss-config)
|
|
|
|
The Tailwind CSS config contains theme that align default config with Vega design system.
|
|
|
|
### [Cypress](./libs/cypress)
|
|
|
|
For shared Cypress logic, commands and steps.
|
|
|
|
### [Web3](./libs/web3)
|
|
|
|
A utility library for connecting to the Ethereum network and interacting with Vega Web3 contracts.
|
|
|
|
### [React Helpers](./libs/react-helpers)
|
|
|
|
Generic react helpers that can be used across multiple applications, along with other utilities.
|
|
|
|
# 💻 Develop
|
|
|
|
### Set up
|
|
|
|
Check you have the correct version of Node. You can [install NVM to switch between node versions](https://github.com/nvm-sh/nvm#installing-and-updating). Then `NVM install`.
|
|
Before you build you will need to `yarn install` in the root directory.
|
|
The repository includes a number of template .env files for different networks. Copy from these to the .env file before `serve` to launch app with different network. You can serve any application with `yarn nx run <name-of-app>:serve`.
|
|
|
|
### Build
|
|
|
|
Run `nx build my-app` to build the project. The build artifacts will be stored in the `dist/` directory. Use the `--prod` flag for a production build.
|
|
|
|
Run `nx serve my-app` for a dev server. Navigate to the port specified in `app/<project-name>/project.json`. The app will automatically reload if you change any of the source files.
|
|
|
|
### Using Apollo GraphQL and Generate Types
|
|
|
|
In order to generate the schemas for your GraphQL queries, you can run `GRAPHQL_SCHEMA_PATH=[YOUR SCHEMA FILE / API URL HERE] nx run types:generate`.
|
|
|
|
```bash
|
|
export GRAPHQL_SCHEMA_PATH=https://api.n07.testnet.vega.xyz/graphql
|
|
yarn nx run types:generate
|
|
```
|
|
|
|
### Running tests
|
|
|
|
Run `yarn nx run <my-app>-e2e:e2e` to execute the e2e tests with [cypress](https://docs.cypress.io/), or `nx affected:e2e` will execute just the end-to-end tests affected by a change. You can use the `--watch` flag to open the cypress tests UI in watch mode, see [cypress executor](https://nx.dev/packages/cypress/executors/cypress) for all CLI flags.
|
|
|
|
Run `nx test my-app` to execute the unit tests with [Jest](https://jestjs.io), or `nx affected:test` to execute just unit tests affected by a change. You can also use `--watch` with these test to run jest in watch mode, see [Jest executor](https://nx.dev/packages/jest/executors/jest) for all CLI flags.
|
|
|
|
### Using wallet
|
|
|
|
To run tests locally using your own wallets make sure you have generated at least two public keys and update the following environment variables in `cypress.config.js` to match your wallet.
|
|
|
|
1. Set `VEGA_PUBLIC_KEY` and `TRUNCATED_VEGA_PUBLIC_KEY` to your first public key.
|
|
2. Set `VEGA_PUBLIC_KEY2` and `TRUNCATED_VEGA_PUBLIC_KEY2` to your second public key.
|
|
3. Set `TRADING_TEST_VEGA_WALLET_PASSPHRASE` as your wallet passphrase
|
|
4. Add `ETH_WALLET_MNEMONIC` as your Ethereum wallet mnemonic
|
|
|
|
### Formatting
|
|
|
|
In CI linting, formatting and also run. These checks can be seen in the [CI workflow file](.github/workflows//test.yml).
|
|
|
|
- To fix linting errors locally run `yarn nx lint --fix`
|
|
- To fix formatting errors local run `yarn nx format:write`
|
|
- For either command you may use `--all` to run across the entire repository
|
|
|
|
### Further help with Nx
|
|
|
|
Visit the [Nx Documentation](https://nx.dev/getting-started/intro) to learn more.
|
|
|
|
# 🐋 Hosting a console
|
|
|
|
To host a console there are two possible build scenarios for running the frontends: nx performed **outside** or **inside** docker build. For specific build instructions follow [build instructions](#build-instructions).
|
|
|
|
In order to run a container on port 3000:
|
|
|
|
```bash
|
|
docker run -p 3000:80 [TAG]
|
|
```
|
|
|
|
On top of that there are two possible scenarios for running docker image - using nginx server (default) of ipfs daemon.
|
|
|
|
to run ipfs on port 3000:
|
|
|
|
```bash
|
|
docker run -p 3000:80 [TAG] /run-ipfs.sh
|
|
```
|
|
|
|
to run nginx on port 3000:
|
|
|
|
```bash
|
|
docker run -p 3000:80 [TAG]
|
|
```
|
|
|
|
## Build instructions
|
|
|
|
The [`docker`](./docker) subfolder has some docker configurations for easily setting up your own hosted version of Console either for the web, or ready for pinning on IPFS.
|
|
|
|
### nx build inside the docker
|
|
|
|
Using multistage dockerfile dist is compiled using [node](https://hub.docker.com/_/node) image and later packed to nginx as in [dist build](#dist-build). The multistage builds ensures consistent CPU architecture and build toolchains are used so that the result will be identical.
|
|
|
|
```bash
|
|
docker build --build-arg APP=[YOUR APP] --build-arg NODE_VERSION=20.9.1 --build-arg ENV_NAME=mainnet -t [TAG] -f docker/node-inside-docker.Dockerfile .
|
|
```
|
|
|
|
### Computing ipfs-hash of the build
|
|
|
|
At the moment this feature is important only for Console releases.
|
|
|
|
Each docker build finishes with hash calculation for ` dist`` directory. Resulting hash is added to file named as `/ipfs-hash`. Once docker image is produced you can run following commad to display ipfs-hash:
|
|
|
|
```bash
|
|
make recalculate-ipfs TAG=vegaprotocol/trading:{YOUR_VERSION}
|
|
```
|
|
|
|
**updating hash:** recompiling dist directory (even if there are no changed to source code) results in different hash computed by ipfs command.
|
|
|
|
### nx build outside the docker
|
|
|
|
This Docker image packages a pre-built `dist` folder into an [`nginx`](https://hub.docker.com/_/nginx)([server configuration](./nginx/nginx.conf)) docker image. In this case, the application on docker host machine from source.
|
|
|
|
As a prerequisite you need to perform build of `dist` directory and move its content for specific application to `dist-result` directory. Use following script to do it with a single command:
|
|
|
|
```bash
|
|
./docker/prepare-dist.sh
|
|
```
|
|
|
|
You can build any of the containers locally with the following command:
|
|
|
|
```bash
|
|
docker build -f docker/node-outside-docker.Dockerfile . --tag=[TAG]
|
|
```
|
|
|
|
### Verifying ipfs-hash of existing current application version
|
|
|
|
An IPFS CID will be attached to every [release](https://github.com/vegaprotocol/frontend-monorepo/releases). If you are intending to pin an application on IPFS, you can check that your build matches by running the following steps:
|
|
|
|
1. Show latest release by running: `make latest-release`. You need to configure [`gh`](https://cli.github.com/) for this step to work, otherwise please provide release manually from [github](https://github.com/vegaprotocol/frontend-monorepo/releases) or [dockerhub](https://hub.docker.com/r/vegaprotocol/trading)
|
|
2. Set RELEASE environment variable to value that you want to validate: `export RELEASE=$(make latest-release)` or `export RELEASE=vXX.XX.XX`
|
|
3. Set TAG environment variable to image that you want to validate: `export TAG=vegaprotocol/trading:$RELEASE`
|
|
4. Download docker image with the desired release `docker pull $TAG`.
|
|
5. Recalculate hash: `make recalculate-ipfs`
|
|
6. You should see exactly same hash produced by ipfs command as one placed with the release notes: `make show-latest-release`
|
|
7. If you want to extract dist from docker image to your local filesystem you can run following command: `make unpack`
|
|
8. Now `dist` directory contains valid application build
|
|
|
|
## Config
|
|
|
|
As environment variables are build time and not run time in frontend applications. We have built a system which allows for passing run time environment variables, this generates a JSON file that will override the default environment variables that the container was built with (which is always testnet, using the default .env files).
|
|
|
|
In order to override specific environment variables you can pass these to the container like this:
|
|
|
|
```bash
|
|
docker run -e NX_VEGA_URL=https://api.n04.d.vega.xyz/graphql -p 3000:80 [TAG]
|
|
```
|
|
|
|
Which will now point the app to use a devnet data node. To see a list of all possible config properties see the readme.md for each app in the app directory.
|
|
|
|
## Vega capsule
|
|
|
|
Coming soon! You will be able to run the containers within Vega Capsule.
|
|
|
|
You can run against a local instance of Vega Capsule today by using the .env.capsule present in the apps.
|
|
|
|
If you wish to run E2E tests for Token and Block Explorer (other areas to be added soon)
|
|
|
|
- Vegacapsule must be used in order for these tests to succeed, the vegacapsule repo README.md file contains the steps required to set this up, it must be installed globally.
|
|
- However we start the capsule network a little differently to how it is laid out in those instructions:
|
|
|
|
In order to run the bootstrap command to generate and start a new network, we must do so using the following:
|
|
|
|
```bash
|
|
vegacapsule network bootstrap --config-path=../frontend-monorepo/vegacapsule/config.hcl
|
|
```
|
|
|
|
In order to setup and run vegawallet for e2e capsule tests, in a separate terminal window:
|
|
|
|
1. cd into `./vegacapsule`
|
|
2. run:
|
|
|
|
```bash
|
|
bash setup-vegawallet.sh
|
|
```
|
|
|
|
3. copy generated `api-token` and paste the token into `CYPRESS_VEGA_WALLET_API_TOKEN` environment variable in either `apps/governance-e2e/.env` or `apps/explorer-e2e/.env` depending on which project needs testing.
|
|
|
|
Note: The script is only needed if capsule was built for first time or fresh. To run existing wallet service for capsule:
|
|
|
|
```bash
|
|
vega wallet service run -n DV --load-tokens --tokens-passphrase-file passphrase --no-version-check --automatic-consent --home ~/.vegacapsule/testnet/wallet
|
|
```
|
|
|
|
# 📑 License
|
|
|
|
[MIT](./LICENSE)
|