Contributing to Meshery UI
UI Contribution Flow
Meshery UI is built on React and Next.js. In nearly all cases, while contributing to Meshery UI, you will need to build and run Meshery Server as well. Meshery Server is written in Go
(Golang) and leverages Go Modules. To make building of each component easier a Makefile
is included in the main repository folder. Use make
to build any and all components.
Architecture
The following is a list of top-level frameworks, libraries, design system used in Meshery UI.
- NextJS - Server and router
- ReactJS - User Interface library
- Material UI - Design System
- BillboardJS - Charting library, used for exposing Grafana and Prometheus-collected metrics
- CytoscapeJS - a visualization tool for canvas-based, visual topology (networks)
Meshery Server APIs
The API overview in the Extensibility guide offers high-level insight, while each API reference (below) offers details pertaining to each API endpointsβ behavior and use.
REST API
Meshery provides a REST API available through the default port of 9081/tcp
at <hostname>:<port>/api/
. See the REST API Reference for a complete list of endpoints available with short description of their purpose and example code.
GraphQL API
Meshery provides a GraphQl API available through the default port of 9081/tcp
at <hostname>:<port>/api/graphql/query
. See the GraphQL API Reference Relay is the client used.
Design
Meshery UI is a significant component of the value proposition Meshery offers to individuals and organizations seeking to adopt and operate a cloud native infrastructure.
User Flows / Wireframing / Mockups
Figma is used as the user flow and UI mockup design tool. The Meshery UI design file can be viewed by using this open invitation for view access. Fill-in a community member form to gain access to additional community resources.
Design Goals
The designs in this specification should result in enabling:
-
User experience should be intuitive - Mesheryβs UX, which includes Meshery UI as a component of the overall UX, needs to be simple, but powerful. This is achieved through intuitive layouts and predefined filters that accommodate common tasks. This is achieved through sensible defaults, consistency of user interaction paradigms and features that delight the user.
-
Extensible - Meshery UI should be a first-class component of Meshery, but also facilitate third-party integrations.
-
Real-time - Meshery UI should be event-driven where possible.
Setup
Windows User?
See Setting up Meshery Development Environment on Windows.Node Version Recommendations
We recommend using Node 18 LTS. Meshery UIβs build script supports other Node versions as well, including node16 and node17, but is recommended to use Node 18 LTS.
Linting-UI
When contributing to Meshery UI, it is advisable to:
- Use prettier and eslint plugin for Visual Studio Code.
- Disable plugins other than
prettier
andeslint
for formatting and linting, if any.
Install UI dependencies
To install/update the UI dependencies:
make ui-setup
Build and export UI
To build and export the UI code:
make ui-build
Using this command, changes that you make are not rebuilt automatically. You will have to run this command again to rebuild the UI and see them.
Now that the UI code is built, Meshery UI will be available at http://localhost:9081
when Meshery Server is running (Read below).
To build and export the UI code and build and run Meshery Server:
make ui-server
Run Meshery Server
To start running Meshery Server locally:
make server
Now, Meshery will run on the default port http://localhost:9081
.
Please note: If you see βMeshery Development Incompatibleβ while trying to sign into Meshery Server, then follow these steps:
Potential Solution:
-
Go to your meshery folder in your local-system where youβve cloned it. Execute:
git remote add upstream https://github.com/meshery/meshery
git fetch upstream
- Restart the meshery server
- Additionally, before restarting the server, if you like to pull the latest changes, you can do:
git pull upstream master
UI Development Server
If you want to work on the UI, it will be a good idea to use the included UI development server. You can run the UI development server by running the following command:
make ui
Refer to Contributing to Meshery Server, if needed.
Make sure to have Meshery Server configured, up and running on the default port
http://localhost:9081
and choose a provider to login with (visithttp://localhost:9081
) before proceeding to access and work on the UI server athttp://localhost:3000
.
Any UI changes made now will automatically be rebuilt and served in your browser.
Running end-to-end integration tests
Refer to Meshery UI Testing for details of how to contribute and benefit from Meshery UI testing.
Static Files, Icons and Images
The Meshery UI public folder contains static files. Its folder structure looks like this:
meshery
βββ ui
βββ public
βββ static
βββ favicon.png
βββ fonts
βββ img
βββ style
Images and icons used in Meshery UI need to be sourced from the public directory of images. The files written inside this directory should only end with the extensions like .svg
, .png
, .jpg
or .jpeg
. Always use vector-based graphics (.svg
), unless your have extenuating circumstances.
Conventions for SVG files
- SVGs should be optimized and compressed.
- Use an online, SVG optimizer, like https://www.svgviewer.dev, to compress the file(s) to smaller size.
- All SVGs should have
height
andwidth
properties set to 20px x 20px by default. Ensure that height and width attributes are always set in original SVG. - All SVGs should have
height
andwidth
included as a style prop in their React component. - Always include this XML header in each SVG image:
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE svg>
- Svg can only fall under two categories, and this categories should be the name of folder
- white: containing white or mono-colored version of that SVG
- color: containing colored version of that SVG.
e.g.: the Meshery logo icon folder structure looks like this:
βββ img βββ meshery βββ white | βββ meshery-white.svg βββ color βββ meshery-color.svg
- Avoid any kind of duplicity in the versions of icons used.
For accessing the svg file as data-url, the utf8 encoding should be used in place of base64.Use encodeURIComponent on SVG data URIs. \
let svg = 'data:image/svg+xml;utf8,' + encodeURIComponent(svgFile);
Suggested Reading
- Build & Release (CI) - Details of Meshery's build and release strategy.
- Contributing to Meshery Adapters - How to contribute to Meshery Adapters
- Contributing to Meshery CLI - How to contribute to Meshery Command Line Interface.
- Contributing to Meshery's End-to-End Tests using Cypress - How to contribute to End-to-End Tests using Cypress.
- Contributing to Meshery Docker Extension - How to contribute to Meshery Docker Extension
- Contributing to Meshery Docs - How to contribute to Meshery Docs.
- How to write MeshKit compatible errors - How to declare errors in Meshery components.
- Contributing to Meshery using git - How to contribute to Meshery using git
- Meshery CLI Contributing Guidelines - Design principles and code conventions.
- Contributing to Model Components - How to contribute to Meshery Model Components
- Contributing to Model Relationships - How to contribute to Meshery Models Relationships, Policies...
- Contributing to Models - How to contribute to Meshery Models, Components, Relationships, Policies...
- Contributing to Meshery Server Events - Guide is to help backend contributors send server events using Golang.
- Contributing to Meshery UI - Notification Center - How to contribute to the Notification Center in Meshery's web-based UI.
- Contributing to Meshery UI - Sistent - How to contribute to the Meshery's web-based UI using sistent design system.
- Contributing to Meshery's End-to-End Tests - How to contribute to End-to-End Tests using Playwright.
- Contributing to Meshery Server - How to contribute to Meshery Server
- Setting up Meshery Development Environment on Windows - How to set up Meshery Development Environment on Windows