Frontend Development Guidelines

This document describes various guidelines to ensure consistency and quality across the GitLab frontend team.

Overview

GitLab is built on top of Ruby on Rails. It uses Haml and a JavaScript-based frontend with Vue.js. If you are not sure when to use Vue on top of Haml-page, please read this explanation.

Be wary of the limitations that come with using Hamlit.

We also use SCSS and plain JavaScript with modern ECMAScript standards supported through Babel and ES module support through webpack.

Working with our frontend assets requires Node (v12.22.1 or greater) and Yarn (v1.10.0 or greater). You can find information on how to install these on our installation guide.

Browser Support

For supported browsers, see our requirements.

Use BrowserStack to test with our supported browsers. Sign in to BrowserStack with the credentials saved in the Engineering vault of the GitLab shared 1Password account.

Initiatives

You can find current frontend initiatives with a cross-functional impact on epics with the label frontend-initiative.

Principles

High-level guidelines for contributing to GitLab.

Development Process

How we plan and execute the work on the frontend.

Architecture

How we go about making fundamental design decisions in the GitLab frontend team or make changes to our frontend development guidelines.

Testing

How we write frontend tests, run the GitLab test suite, and debug test related issues.

Pajamas Design System

Reusable components with technical and usage guidelines can be found in our Pajamas Design System.

Design Patterns

JavaScript design patterns in the GitLab codebase.

Design Anti-patterns

JavaScript design anti-patterns we try to avoid.

Vue.js Best Practices

Vue specific design patterns and practices.

Vuex

Vuex specific design patterns and practices.

Axios

Axios specific practices and gotchas.

GraphQL

How to use GraphQL.

HAML

How to use HAML.

ViewComponent

How we use ViewComponent.

Icons and Illustrations

How we use SVG for our Icons and Illustrations.

Dependencies

General information about frontend dependencies and how we manage them.

Keyboard Shortcuts

How we implement keyboard shortcuts that can be customized and disabled.

Editors

GitLab text editing experiences are provided by the Source Editor and the Content Editor.

Frontend FAQ

Read the frontend’s FAQ for common small pieces of helpful information.

Style Guides

See the relevant style guides for our guidelines and for information on linting:

  • JavaScript. Our guide is based on the excellent Airbnb style guide with a few small changes.
  • SCSS: our SCSS conventions which are enforced through stylelint.
  • HTML. Guidelines for writing HTML code consistent with the rest of the codebase.
  • Vue. Guidelines and conventions for Vue code may be found here.

Tooling

Our code is automatically formatted with Prettier to follow our guidelines. Read our Tooling guide for more detail.

Performance

Best practices for monitoring and maximizing frontend performance.

Security

Frontend security practices.

Accessibility

Our accessibility standards and resources.

Logging

Best practices for client-side logging for GitLab frontend development.

Internationalization (i18n) and Translations

Frontend internationalization support is described in this document. The externalization part of the guide explains the helpers/methods available.

Troubleshooting

Running into a Frontend development problem? Check out this guide to help resolve your issue.