7.5 KiB
Frontend Development Guidelines
This document describes various guidelines to ensure consistency and quality across GitLab's frontend.
Performance
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
:
- Create a directory for the specific page(s), e.g.
graphs/
. - In that directory, create a
namespace_bundle.js
file, e.g.graphs_bundle.js
. - In
graphs_bundle.js
add the line//= require_tree .
, this adds all other files in the directory to the bundle. - Add any necessary libraries to
app/assets/javascripts/lib/
, all files directly descendant from this directory will be precompiled as separate assets, in this casechart.js
would be added. - Add the new "bundle" file to the list of precompiled assets in
config/application.rb
.
- For example:
config.assets.precompile << "graphs/graphs_bundle.js"
.
- Move code reliant on these libraries into the
graphs
directory. - 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 only this page. 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.
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 unnecessary fonts.
- Prefer font formats with better compression, e.g. WOFF2 is better than WOFF is better than TFF.
- Compress and minify assets wherever possible (For CSS/JS, Sprockets does this for us).
- If a piece of functionality can be reasonably done without adding extra libraries, prefer not to use extra libraries.
- Use page-specific JavaScripts as described above to dynamically load libraries that are only needed on certain pages.
Accessibility
The 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
[Mozilla’s HTTP Observatory CLI][observatory-cli] and the [Qualys SSL Labs Server Test][qualys-ssl] 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][xss], our intention is to disable inline scripts entirely using Content Security Policy at some point in the future.
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 site.
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 details and information on linting:
- [SCSS][scss-style-guide]
[observatory-cli]: https://github.com/mozilla/http-observatory-cli) [qualys-ssl]: https://www.ssllabs.com/ssltest/analyze.html [secure_headers]: https://github.com/twitter/secureheaders [mdn-csp]: https://developer.mozilla.org/en-US/docs/Web/Security/CSP [github-eng-csp]: http://githubengineering.com/githubs-csp-journey/ [dropbox-csp-1]: https://blogs.dropbox.com/tech/2015/09/on-csp-reporting-and-filtering/ [dropbox-csp-2]: https://blogs.dropbox.com/tech/2015/09/unsafe-inline-and-nonce-deployment/ [dropbox-csp-3]: https://blogs.dropbox.com/tech/2015/09/csp-the-unexpected-eval/ [dropbox-csp-4]: https://blogs.dropbox.com/tech/2015/09/csp-third-party-integrations-and-privilege-separation/ [mdn-sri]: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity [github-eng-sri]: http://githubengineering.com/subresource-integrity/ [sprockets-sri]: https://github.com/rails/sprockets-rails#sri-support [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting [scss-style-guide]: scss_styleguide.md