GitLab Documentation

Frontend Development Guidelines

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

Overview

GitLab is built on top of Ruby on Rails using Haml with Hamlit. Be wary of the limitations that come with using Hamlit. We also use SCSS and plain JavaScript with ES6 by way of Babel.

The asset pipeline is Sprockets, which handles the concatenation, minification, and compression of our assets.

jQuery is used throughout the application's JavaScript, with Vue.js for particularly advanced, dynamic elements.

Architecture

The Frontend Architect is an expert who makes high-level frontend design choices and decides on technical standards, including coding standards, and frameworks.

When you are assigned a new feature that requires architectural design, make sure it is discussed with one of the Frontend Architecture Experts.

This rule also applies if you plan to change the architecture of an existing feature.

These decisions should be accessible to everyone, so please document it on the Merge Request.

You can find the Frontend Architecture experts on the team page.

You can find documentation about the desired architecture for a new feature built with Vue.js in here.

Realtime

When writing code for realtime features we have to keep a couple of things in mind:

  1. Do not overload the server with requests.
  2. It should feel realtime.

Thus, we must strike a balance between sending requests and the feeling of realtime. Use the following rules when creating realtime solutions.

  1. The server will tell you how much to poll by sending Poll-Interval in the header. Use that as your polling interval. This way it is easy for system administrators to change the polling rate. A Poll-Interval: -1 means you should disable polling, and this must be implemented.
  2. A response with HTTP status 4XX or 5XX should disable polling as well.
  3. Use a common library for polling.
  4. Poll on active tabs only. Use a common library to find out which tab currently has eyes on it. Please use Focus. Specifically Eyeballs Detector.
  5. Use regular polling intervals, do not use backoff polling, or jitter, as the interval will be controlled by the server.
  6. The backend code will most likely be using etags. You do not and should not check for status 304 Not Modified. The browser will transform it for you.

Vue

For more complex frontend features, we recommend using Vue.js. It shares some ideas with React.js as well as Angular.

To get started with Vue, read through their documentation.

How to build a new feature with Vue.js

Components, Stores and Services

In some features implemented with Vue.js, like the issue board or environments table you can find a clear separation of concerns:

new_feature
├── components
│   └── component.js.es6
│   └── ...
├── store
│  └── new_feature_store.js.es6
├── service
│  └── new_feature_service.js.es6
├── new_feature_bundle.js.es6

For consistency purposes, we recommend you to follow the same structure.

Let's look into each of them:

A *_bundle.js file

This is the index file of your new feature. This is where the root Vue instance of the new feature should be.

The Store and the Service should be imported and initialized in this file and provided as a prop to the main component.

Don't forget to follow these steps.

A folder for Components

This folder holds all components that are specific of this new feature. If you need to use or create a component that will probably be used somewhere else, please refer to vue_shared/components.

A good thumb rule to know when you should create a component is to think if it will be reusable elsewhere.

For example, tables are used in a quite amount of places across GitLab, a table would be a good fit for a component. On the other hand, a table cell used only in on table, would not be a good use of this pattern.

You can read more about components in Vue.js site, Component System

A folder for the Store

The Store is a class that allows us to manage the state in a single source of truth.

The concept we are trying to follow is better explained by Vue documentation itself, please read this guide: State Management

A folder for the Service

The Service is used only to communicate with the server. It does not store or manipulate any data. We use vue-resource to communicate with the server.

The issue boards service is a good example of this pattern.

Performance

Resources

Page-specific JavaScript

Certain pages may require the use of a third party library, such as d3 for the User Activity Calendar and Chart.js for the Graphs pages. These libraries increase the page size significantly, and impact load times due to bandwidth bottlenecks and the browser needing to parse more JavaScript.

In cases where libraries are only used on a few specific pages, we use "page-specific JavaScript" to prevent the main application.js file from becoming unnecessarily large.

Steps to split page-specific JavaScript from the main application.js:

  1. Create a directory for the specific page(s), e.g. graphs/.
  2. In that directory, create a namespace_bundle.js file, e.g. graphs_bundle.js.
  3. In graphs_bundle.js add the line //= require_tree ., this adds all other files in the directory to the bundle.
  4. Add any necessary libraries to app/assets/javascripts/lib/, all files directly descendant from this directory will be precompiled as separate assets, in this case chart.js would be added.
  5. Add the new "bundle" file to the list of precompiled assets in config/application.rb.
    • For example: config.assets.precompile << "graphs/graphs_bundle.js".
  6. Move code reliant on these libraries into the graphs directory.
  7. In the relevant views, add the scripts to the page with the following:
- content_for :page_specific_javascripts do
  = page_specific_javascript_tag('lib/chart.js')
  = page_specific_javascript_tag('graphs/graphs_bundle.js')

The above loads chart.js and graphs_bundle.js for this page only. chart.js is separated from the bundle file so it can be cached separately from the bundle and reused for other pages that also rely on the library. For an example, see this Haml file.

Minimizing page size

A smaller page size means the page loads faster (especially important on mobile and poor connections), the page is parsed more quickly by the browser, and less data is used for users with capped data plans.

General tips:

Accessibility

Resources

Chrome Accessibility Developer Tools are useful for testing for potential accessibility problems in GitLab.

Accessibility best-practices and more in-depth information is available on the Audit Rules page for the Chrome Accessibility Developer Tools.

Security

Resources

Mozilla’s HTTP Observatory CLI and the Qualys SSL Labs Server Test are good resources for finding potential problems and ensuring compliance with security best practices.

Including external resources

External fonts, CSS, and JavaScript should never be used with the exception of Google Analytics and Piwik - and only when the instance has enabled it. Assets should always be hosted and served locally from the GitLab instance. Embedded resources via iframes should never be used except in certain circumstances such as with ReCaptcha, which cannot be used without an iframe.

Avoiding inline scripts and styles

In order to protect users from XSS vulnerabilities, we will disable inline scripts in the future using Content Security Policy.

While inline scripts can be useful, they're also a security concern. If user-supplied content is unintentionally left un-sanitized, malicious users can inject scripts into the web app.

Inline styles should be avoided in almost all cases, they should only be used when no alternatives can be found. This allows reusability of styles as well as readability.

Style guides and linting

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

Testing

Feature tests need to be written for all new features. Regression tests also need to be written for all bug fixes to prevent them from occurring again in the future.

See the Testing Standards and Style Guidelines for more information.

Running frontend tests

rake karma runs the frontend-only (JavaScript) tests. It consists of two subtasks:

As long as the fixtures don't change, rake karma:tests is sufficient (and saves you some time).

Please note: Not all of the frontend fixtures are generated. Some are still static files. These will not be touched by rake karma:fixtures.

Design Patterns

Singletons

When exactly one object is needed for a given task, prefer to define it as a class rather than as an object literal. Prefer also to explicitly restrict instantiation, unless flexibility is important (e.g. for testing).

// bad

gl.MyThing = {
  prop1: 'hello',
  method1: () => {}
};

// good

class MyThing {
  constructor() {
    this.prop1 = 'hello';
  }
  method1() {}
}

gl.MyThing = new MyThing();

// best

let singleton;

class MyThing {
  constructor() {
    if (!singleton) {
      singleton = this;
      singleton.init();
    }
      return singleton;
  }

  init() {
    this.prop1 = 'hello';
  }

  method1() {}
}

gl.MyThing = MyThing;

Manipulating the DOM in a JS Class

When writing a class that needs to manipulate the DOM guarantee a container option is provided. This is useful when we need that class to be instantiated more than once in the same page.

Bad:

class Foo {
  constructor() {
    document.querySelector('.bar');
  }
}
new Foo();

Good:

class Foo {
  constructor(opts) {
    document.querySelector(`${opts.container} .bar`);
  }
}

new Foo({ container: '.my-element' });

You can find an example of the above in this class;

Supported browsers

For our currently-supported browsers, see our requirements.

Gotchas

Spec errors due to use of ES6 features in .js files

If you see very generic JavaScript errors (e.g. jQuery is undefined) being thrown in Karma, Spinach, or Rspec tests but can't reproduce them manually, you may have included ES6-style JavaScript in files that don't have the .js.es6 file extension. Either use ES5-friendly JavaScript or rename the file you're working in (git mv <file.js> <file.js.es6>).

Spec errors due to use of unsupported JavaScript

Similar errors will be thrown if you're using JavaScript features not yet supported by our test runner's version of webkit, whether or not you've updated the file extension. Examples of unsupported JavaScript features are:

Until these are polyfilled or transpiled appropriately, they should not be used. Please update this list with additional unsupported features or when any of these are made usable.

Spec errors due to JavaScript not enabled

If, as a result of a change you've made, a feature now depends on JavaScript to run correctly, you need to make sure a JavaScript web driver is enabled when specs are run. If you don't you'll see vague error messages from the spec runner, and an explosion of vague console errors in the HTML snapshot.

To enable a JavaScript driver in an rspec test, add js: true to the individual spec or the context block containing multiple specs that need JavaScript enabled:


# For one spec
it 'presents information about abuse report', js: true do
    # assertions...
end

describe "Admin::AbuseReports", js: true do
   it 'presents information about abuse report' do
        # assertions...
    end
   it 'shows buttons for adding to abuse report' do
        # assertions...
    end
end

In Spinach, the JavaScript driver is enabled differently. In the *.feature file for the failing spec, add the @javascript flag above the Scenario:

@javascript
Scenario: Developer can approve merge request
    Given I am a "Shop" developer
    And I visit project "Shop" merge requests page
    And merge request 'Bug NS-04' must be approved
    And I click link "Bug NS-04"
    When I click link "Approve"
    Then I should see approved merge request "Bug NS-04"