PageRenderTime 33ms CodeModel.GetById 34ms RepoModel.GetById 0ms app.codeStats 0ms

Markdown | 312 lines | 223 code | 89 blank | 0 comment | 0 complexity | 8fa61f2eefd196b5bad7ee21f5b66afe MD5 | raw file
  1. # Frontend Development Guidelines
  2. This document describes various guidelines to ensure consistency and quality
  3. across GitLab's frontend team.
  4. ## Overview
  5. GitLab is built on top of [Ruby on Rails][rails] using [Haml][haml] with
  6. [Hamlit][hamlit]. Be wary of [the limitations that come with using
  7. Hamlit][hamlit-limits]. We also use [SCSS][scss] and plain JavaScript with
  8. [ES6 by way of Babel][es6].
  9. The asset pipeline is [Sprockets][sprockets], which handles the concatenation,
  10. minification, and compression of our assets.
  11. [jQuery][jquery] is used throughout the application's JavaScript, with
  12. [Vue.js][vue] for particularly advanced, dynamic elements.
  13. ### Vue
  14. For more complex frontend features, we recommend using Vue.js. It shares
  15. some ideas with React.js as well as Angular.
  16. To get started with Vue, read through [their documentation][vue-docs].
  17. ## Performance
  18. ### Resources
  19. - [WebPage Test][web-page-test] for testing site loading time and size.
  20. - [Google PageSpeed Insights][pagespeed-insights] grades web pages and provides feedback to improve the page.
  21. - [Profiling with Chrome DevTools][google-devtools-profiling]
  22. - [Browser Diet][browser-diet] is a community-built guide that catalogues practical tips for improving web page performance.
  23. ### Page-specific JavaScript
  24. Certain pages may require the use of a third party library, such as [d3][d3] for
  25. the User Activity Calendar and [Chart.js][chartjs] for the Graphs pages. These
  26. libraries increase the page size significantly, and impact load times due to
  27. bandwidth bottlenecks and the browser needing to parse more JavaScript.
  28. In cases where libraries are only used on a few specific pages, we use
  29. "page-specific JavaScript" to prevent the main `application.js` file from
  30. becoming unnecessarily large.
  31. Steps to split page-specific JavaScript from the main `application.js`:
  32. 1. Create a directory for the specific page(s), e.g. `graphs/`.
  33. 1. In that directory, create a `namespace_bundle.js` file, e.g. `graphs_bundle.js`.
  34. 1. In `graphs_bundle.js` add the line `//= require_tree .`, this adds all other files in the directory to the bundle.
  35. 1. 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.
  36. 1. Add the new "bundle" file to the list of precompiled assets in
  37. `config/application.rb`.
  38. - For example: `config.assets.precompile << "graphs/graphs_bundle.js"`.
  39. 1. Move code reliant on these libraries into the `graphs` directory.
  40. 1. In the relevant views, add the scripts to the page with the following:
  41. ```haml
  42. - content_for :page_specific_javascripts do
  43. = page_specific_javascript_tag('lib/chart.js')
  44. = page_specific_javascript_tag('graphs/graphs_bundle.js')
  45. ```
  46. The above loads `chart.js` and `graphs_bundle.js` for this page only. `chart.js`
  47. is separated from the bundle file so it can be cached separately from the bundle
  48. and reused for other pages that also rely on the library. For an example, see
  49. [this Haml file][page-specific-js-example].
  50. ### Minimizing page size
  51. A smaller page size means the page loads faster (especially important on mobile
  52. and poor connections), the page is parsed more quickly by the browser, and less
  53. data is used for users with capped data plans.
  54. General tips:
  55. - Don't add new fonts.
  56. - Prefer font formats with better compression, e.g. WOFF2 is better than WOFF, which is better than TTF.
  57. - Compress and minify assets wherever possible (For CSS/JS, Sprockets does this for us).
  58. - If some functionality can reasonably be achieved without adding extra libraries, avoid them.
  59. - Use page-specific JavaScript as described above to dynamically load libraries that are only needed on certain pages.
  60. ## Accessibility
  61. ### Resources
  62. [Chrome Accessibility Developer Tools][chrome-accessibility-developer-tools]
  63. are useful for testing for potential accessibility problems in GitLab.
  64. Accessibility best-practices and more in-depth information is available on
  65. [the Audit Rules page][audit-rules] for the Chrome Accessibility Developer Tools.
  66. ## Security
  67. ### Resources
  68. [Mozillas HTTP Observatory CLI][observatory-cli] and the
  69. [Qualys SSL Labs Server Test][qualys-ssl] are good resources for finding
  70. potential problems and ensuring compliance with security best practices.
  71. <!-- Uncomment these sections when CSP/SRI are implemented.
  72. ### Content Security Policy (CSP)
  73. Content Security Policy is a web standard that intends to mitigate certain
  74. forms of Cross-Site Scripting (XSS) as well as data injection.
  75. Content Security Policy rules should be taken into consideration when
  76. implementing new features, especially those that may rely on connection with
  77. external services.
  78. GitLab's CSP is used for the following:
  79. - Blocking plugins like Flash and Silverlight from running at all on our pages.
  80. - Blocking the use of scripts and stylesheets downloaded from external sources.
  81. - Upgrading `http` requests to `https` when possible.
  82. - Preventing `iframe` elements from loading in most contexts.
  83. Some exceptions include:
  84. - Scripts from Google Analytics and Piwik if either is enabled.
  85. - Connecting with GitHub, Bitbucket,, etc. to allow project importing.
  86. - Connecting with Google, Twitter, GitHub, etc. to allow OAuth authentication.
  87. We use [the Secure Headers gem][secure_headers] to enable Content
  88. Security Policy headers in the GitLab Rails app.
  89. Some resources on implementing Content Security Policy:
  90. - [MDN Article on CSP][mdn-csp]
  91. - [GitHubs CSP Journey on the GitHub Engineering Blog][github-eng-csp]
  92. - The Dropbox Engineering Blog's series on CSP: [1][dropbox-csp-1], [2][dropbox-csp-2], [3][dropbox-csp-3], [4][dropbox-csp-4]
  93. ### Subresource Integrity (SRI)
  94. Subresource Integrity prevents malicious assets from being provided by a CDN by
  95. guaranteeing that the asset downloaded is identical to the asset the server
  96. is expecting.
  97. The Rails app generates a unique hash of the asset, which is used as the
  98. asset's `integrity` attribute. The browser generates the hash of the asset
  99. on-load and will reject the asset if the hashes do not match.
  100. All CSS and JavaScript assets should use Subresource Integrity. For implementation details,
  101. see the documentation for [the Sprockets implementation of SRI][sprockets-sri].
  102. Some resources on implementing Subresource Integrity:
  103. - [MDN Article on SRI][mdn-sri]
  104. - [Subresource Integrity on the GitHub Engineering Blog][github-eng-sri]
  105. -->
  106. ### Including external resources
  107. External fonts, CSS, and JavaScript should never be used with the exception of
  108. Google Analytics and Piwik - and only when the instance has enabled it. Assets
  109. should always be hosted and served locally from the GitLab instance. Embedded
  110. resources via `iframes` should never be used except in certain circumstances
  111. such as with ReCaptcha, which cannot be used without an `iframe`.
  112. ### Avoiding inline scripts and styles
  113. In order to protect users from [XSS vulnerabilities][xss], we will disable inline scripts in the future using Content Security Policy.
  114. While inline scripts can be useful, they're also a security concern. If
  115. user-supplied content is unintentionally left un-sanitized, malicious users can
  116. inject scripts into the web app.
  117. Inline styles should be avoided in almost all cases, they should only be used
  118. when no alternatives can be found. This allows reusability of styles as well as
  119. readability.
  120. ## Style guides and linting
  121. See the relevant style guides for our guidelines and for information on linting:
  122. - [SCSS][scss-style-guide]
  123. ## Testing
  124. Feature tests need to be written for all new features. Regression tests
  125. also need to be written for all bug fixes to prevent them from occurring
  126. again in the future.
  127. See [the Testing Standards and Style Guidelines]( for more
  128. information.
  129. ### Running frontend tests
  130. `rake teaspoon` runs the frontend-only (JavaScript) tests.
  131. It consists of two subtasks:
  132. - `rake teaspoon:fixtures` (re-)generates fixtures
  133. - `rake teaspoon:tests` actually executes the tests
  134. As long as the fixtures don't change, `rake teaspoon:tests` is sufficient
  135. (and saves you some time).
  136. If you need to debug your tests and/or application code while they're
  137. running, navigate to [localhost:3000/teaspoon](http://localhost:3000/teaspoon)
  138. in your browser, open DevTools, and run tests for individual files by clicking
  139. on them. This is also much faster than setting up and running tests from the
  140. command line.
  141. Please note: Not all of the frontend fixtures are generated. Some are still static
  142. files. These will not be touched by `rake teaspoon:fixtures`.
  143. ## Design Patterns
  144. ### Singletons
  145. When exactly one object is needed for a given task, prefer to define it as a
  146. `class` rather than as an object literal. Prefer also to explicitly restrict
  147. instantiation, unless flexibility is important (e.g. for testing).
  148. ```
  149. // bad
  150. gl.MyThing = {
  151. prop1: 'hello',
  152. method1: () => {}
  153. };
  154. // good
  155. class MyThing {
  156. constructor() {
  157. this.prop1 = 'hello';
  158. }
  159. method1() {}
  160. }
  161. gl.MyThing = new MyThing();
  162. // best
  163. let singleton;
  164. class MyThing {
  165. constructor() {
  166. if (!singleton) {
  167. singleton = this;
  168. singleton.init();
  169. }
  170. return singleton;
  171. }
  172. init() {
  173. this.prop1 = 'hello';
  174. }
  175. method1() {}
  176. }
  177. gl.MyThing = MyThing;
  178. ```
  179. ## Supported browsers
  180. For our currently-supported browsers, see our [requirements][requirements].
  181. [rails]:
  182. [haml]:
  183. [hamlit]:
  184. [hamlit-limits]:
  185. [scss]:
  186. [es6]:
  187. [sprockets]:
  188. [jquery]:
  189. [vue]:
  190. [vue-docs]:
  191. [web-page-test]:
  192. [pagespeed-insights]:
  193. [google-devtools-profiling]:
  194. [browser-diet]:
  195. [d3]:
  196. [chartjs]:
  197. [page-specific-js-example]:
  198. [chrome-accessibility-developer-tools]:
  199. [audit-rules]:
  200. [observatory-cli]:
  201. [qualys-ssl]:
  202. [secure_headers]:
  203. [mdn-csp]:
  204. [github-eng-csp]:
  205. [dropbox-csp-1]:
  206. [dropbox-csp-2]:
  207. [dropbox-csp-3]:
  208. [dropbox-csp-4]:
  209. [mdn-sri]:
  210. [github-eng-sri]:
  211. [sprockets-sri]:
  212. [xss]:
  213. [scss-style-guide]:
  214. [requirements]: ../install/
  215. ## Gotchas
  216. ### Phantom.JS (used by Teaspoon & Rspec) chokes, returning vague JavaScript errors
  217. If you see very generic JavaScript errors (e.g. `jQuery is undefined`) being thrown in tests, but
  218. can't reproduce them manually, you may have included `ES6`-style JavaScript in files that don't
  219. have the `.js.es6` file extension. Either use ES5-friendly JavaScript or rename the file you're
  220. working in (`git mv <file.js> <file.js.es6>`).
  221. Similar errors will be thrown if you're using
  222. any of the [array methods introduced in ES6](
  223. whether or not you've updated the file extension.