Performance

Best Practices

Realtime Components

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 different from 2XX should disable polling as well.
  3. Use a common library for polling.
  4. Poll on active tabs only. Please use Visibility.
  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.

Lazy Loading Images

To improve the time to first render we are using lazy loading for images. This works by setting the actual image source on the data-src attribute. After the HTML is rendered and JavaScript is loaded, the value of data-src will be moved to src automatically if the image is in the current viewport.

If you are asynchronously adding content which contains lazy images then you need to call the function gl.lazyLoader.searchLazyImages() which will search for lazy images and load them if needed. But in general it should be handled automatically through a MutationObserver in the lazy loading function.

Animations

Only animate opacity & transform properties. Other properties (such as top, left, margin, and padding) all cause Layout to be recalculated, which is much more expensive. For details on this, see "Styles that Affect Layout" in High Performance Animations.

If you do need to change layout (e.g. a sidebar that pushes main content over), prefer FLIP to change expensive properties once, and handle the actual animation with transforms.

Reducing Asset Footprint

Universal code

Code that is contained within main.js and commons/index.js are loaded and run on all pages. DO NOT ADD anything to these files unless it is truly needed everywhere. These bundles include ubiquitous libraries like vue, axios, and jQuery, as well as code for the main navigation and sidebar. Where possible we should aim to remove modules from these bundles to reduce our code footprint.

Page-specific JavaScript

Webpack has been configured to automatically generate entry point bundles based on the file structure within app/assets/javascripts/pages/*. The directories within the pages directory correspond to Rails controllers and actions. These auto-generated bundles will be automatically included on the corresponding pages.

For example, if you were to visit https://gitlab.com/gitlab-org/gitlab/issues, you would be accessing the app/controllers/projects/issues_controller.rb controller with the index action. If a corresponding file exists at pages/projects/issues/index/index.js, it will be compiled into a webpack bundle and included on the page.

NOTE: Note: Previously we had encouraged the use of content_for :page_specific_javascripts within haml files, along with manually generated webpack bundles. However under this new system you should not ever need to manually add an entry point to the webpack.config.js file.

TIP: Tip: If you are unsure what controller and action corresponds to a given page, you can find this out by inspecting document.body.dataset.page within your browser's developer console while on any page within GitLab.

Important Considerations

```javascript import initMyWidget from './my_widget';

document.addEventListener('DOMContentLoaded', () => { initMyWidget(); }); ```

Code Splitting

For any code that does not need to be run immediately upon page load, (e.g. modals, dropdowns, and other behaviors that can be lazy-loaded), you can split your module into asynchronous chunks with dynamic import statements. These imports return a Promise which will be resolved once the script has loaded:

import(/* webpackChunkName: 'emoji' */ '~/emoji')
  .then(/* do something */)
  .catch(/* report error */)

Please try to use webpackChunkName when generating these dynamic imports as it will provide a deterministic filename for the chunk which can then be cached the browser across GitLab versions.

More information is available in webpack's code splitting documentation.

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:

Additional Resources