90 lines
4.6 KiB
Markdown
90 lines
4.6 KiB
Markdown
---
|
|
stage: Package
|
|
group: unassigned
|
|
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
|
|
---
|
|
|
|
# Registry architecture
|
|
|
|
GitLab has several registry applications. Given that they all leverage similar UI, UX, and business
|
|
logic, they are all built with the same architecture. In addition, a set of shared components
|
|
already exists to unify the user and developer experiences.
|
|
|
|
Existing registries:
|
|
|
|
- Package Registry
|
|
- Container Registry
|
|
- Infrastructure Registry
|
|
- Dependency Proxy
|
|
|
|
## Frontend architecture
|
|
|
|
### Component classification
|
|
|
|
All the registries follow an architecture pattern that includes four component types:
|
|
|
|
- Pages: represent an entire app, or for the registries using [vue-router](https://v3.router.vuejs.org/) they represent one router
|
|
route.
|
|
- Containers: represent a single piece of functionality. They contain complex logic and may
|
|
connect to the API.
|
|
- Presentationals: represent a portion of the UI. They receive all their data with `props` or through
|
|
`inject`, and do not connect to the API.
|
|
- Shared components: presentational components that accept a various array of configurations and are
|
|
shared across all of the registries.
|
|
|
|
### Communicating with the API
|
|
|
|
The complexity and communication with the API should be concentrated in the pages components, and
|
|
in the container components when needed. This makes it easier to:
|
|
|
|
- Handle concurrent requests, loading states, and user messages.
|
|
- Maintain the code, especially to estimate work. If it touches a page or functional component,
|
|
expect it to be more complex.
|
|
- Write fast and consistent unit tests.
|
|
|
|
### Best practices
|
|
|
|
- Use [`provide` or `inject`](https://v2.vuejs.org/v2/api/?redirect=true#provide-inject)
|
|
to pass static, non-reactive values coming from the app initialization.
|
|
- When passing data, prefer `props` over nested queries or Vuex bindings. Only pages and
|
|
container components should be aware of the state and API communication.
|
|
- Don't repeat yourself. If one registry receives functionality, the likelihood of the rest needing
|
|
it in the future is high. If something seems reusable and isn't bound to the state, create a
|
|
shared component.
|
|
- Try to express functionality and logic with dedicated components. It's much easier to deal with
|
|
events and properties than callbacks and asynchronous code (see
|
|
[`delete_package.vue`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/packages_and_registries/package_registry/components/functional/delete_package.vue)).
|
|
- Leverage [startup for GraphQL calls](graphql.md#making-initial-queries-early-with-graphql-startup-calls).
|
|
|
|
## Shared components library
|
|
|
|
Inside `vue_shared/components/registry` and `packages_and_registries/shared`, there's a set of
|
|
shared components that you can use to implement registry functionality. These components build the
|
|
main pieces of the desired UI and UX of a registry page. The most important components are:
|
|
|
|
- `code-instruction`: represents a copyable box containing code. Supports multiline and single line
|
|
code boxes. Snowplow tracks the code copy event.
|
|
- `details-row`: represents a row of details. Used to add additional information in the details area of
|
|
the `list-item` component.
|
|
- `history-item`: represents a history list item used to build a timeline.
|
|
- `list-item`: represents a list element in the registry. It supports: left action, left primary and
|
|
secondary content, right primary and secondary content, right action, and details slots.
|
|
- `metadata-item`: represents one piece of metadata, with an icon or a link. Used primarily in the
|
|
title area.
|
|
- `persisted-dropdown-selection`: represents a dropdown menu that stores the user selection in the
|
|
`localStorage`.
|
|
- `registry-search`: implements `gl-filtered-search` with a sorting section on the right.
|
|
- `title-area`: implements the top title area of the registry. Includes: a main title, an avatar, a
|
|
subtitle, a metadata row, and a right actions slot.
|
|
|
|
## Adding a new registry page
|
|
|
|
When adding a new registry:
|
|
|
|
- Leverage the shared components that already exist. It's good to look at how the components are
|
|
structured and used in the more mature registries (for example, the Package Registry).
|
|
- If it's in line with the backend requirements, we suggest using GraphQL for the API. This helps in
|
|
dealing with the innate performance issue of registries.
|
|
- If possible, we recommend using [Vue Router](https://v3.router.vuejs.org/)
|
|
and frontend routing. Coupled with Apollo, the caching layer helps with the perceived page
|
|
performance.
|