8.6 KiB
Performance
Best Practices
Realtime Components
When writing code for realtime features we have to keep a couple of things in mind:
- Do not overload the server with requests.
- 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.
- 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. APoll-Interval: -1
means you should disable polling, and this must be implemented. - A response with HTTP status different from 2XX should disable polling as well.
- Use a common library for polling.
- Poll on active tabs only. Please use Visibility.
- Use regular polling intervals, do not use backoff polling, or jitter, as the interval will be controlled by the server.
- 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.
- Prepare images in HTML for lazy loading by renaming the
src
attribute todata-src
AND adding the classlazy
. - If you are using the Rails
image_tag
helper, all images will be lazy-loaded by default unlesslazy: false
is provided.
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 gitlab.com/gitlab-org/gitlab-foss/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: 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 thewebpack.config.js
file.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
-
Keep Entry Points Lite: Page-specific javascript entry points should be as lite as possible. These files are exempt from unit tests, and should be used primarily for instantiation and dependency injection of classes and methods that live in modules outside of the entry point script. Just import, read the DOM, instantiate, and nothing else.
-
Entry Points May Be Asynchronous: DO NOT ASSUME that the DOM has been fully loaded and available when an entry point script is run. If you require that some code be run after the DOM has loaded, you should attach an event handler to the
DOMContentLoaded
event with:import initMyWidget from './my_widget'; document.addEventListener('DOMContentLoaded', () => { initMyWidget(); });
-
Supporting Module Placement:
- If a class or a module is specific to a particular route, try to locate
it close to the entry point it will be used. For instance, if
my_widget.js
is only imported withinpages/widget/show/index.js
, you should place the module atpages/widget/show/my_widget.js
and import it with a relative path (e.g.import initMyWidget from './my_widget';
). - If a class or module is used by multiple routes, place it within a
shared directory at the closest common parent directory for the entry
points that import it. For example, if
my_widget.js
is imported within bothpages/widget/show/index.js
andpages/widget/run/index.js
, then place the module atpages/widget/shared/my_widget.js
and import it with a relative path if possible (e.g.../shared/my_widget
).
- If a class or a module is specific to a particular route, try to locate
it close to the entry point it will be used. For instance, if
-
Enterprise Edition Caveats: For GitLab Enterprise Edition, page-specific entry points will override their Community Edition counterparts with the same name, so if
ee/app/assets/javascripts/pages/foo/bar/index.js
exists, it will take precedence overapp/assets/javascripts/pages/foo/bar/index.js
. If you want to minimize duplicate code, you can import one entry point from the other. This is not done automatically to allow for flexibility in overriding functionality.
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:
- Don't add new fonts.
- Prefer font formats with better compression, e.g. WOFF2 is better than WOFF, which is better than TTF.
- Compress and minify assets wherever possible (For CSS/JS, Sprockets and webpack do this for us).
- If some functionality can reasonably be achieved without adding extra libraries, avoid them.
- Use page-specific JavaScript as described above to load libraries that are only needed on certain pages.
- Use code-splitting dynamic imports wherever possible to lazy-load code that is not needed initially.
- High Performance Animations
Additional Resources
- WebPage Test for testing site loading time and size.
- Google PageSpeed Insights grades web pages and provides feedback to improve the page.
- Profiling with Chrome DevTools
- Browser Diet is a community-built guide that catalogues practical tips for improving web page performance.