gitlab-org--gitlab-foss/doc/development/fe_guide/index.md

---
stage: none
group: unassigned
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---

# 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](https://rubyonrails.org) using [Haml](https://haml.info/) and also a JavaScript based Frontend with [Vue.js](https://vuejs.org).
Be wary of [the limitations that come with using Hamlit](https://github.com/k0kubun/hamlit/blob/master/REFERENCE.md#limitations). We also use [SCSS](https://sass-lang.com) and plain JavaScript with
modern ECMAScript standards supported through [Babel](https://babeljs.io/) and ES module support through [webpack](https://webpack.js.org/).

Working with our frontend assets requires Node (v10.13.0 or greater) and Yarn
(v1.10.0 or greater). You can find information on how to install these on our
[installation guide](../../install/installation.md#4-node).

### Browser Support

For our currently-supported browsers, see our [requirements](../../install/requirements.md#supported-web-browsers).

Use [BrowserStack](https://www.browserstack.com/) to test with our supported browsers.
Sign in to BrowserStack with the credentials saved in the **Engineering** vault of GitLab's
[shared 1Password account](https://about.gitlab.com/handbook/security/#1password-guide).

## Initiatives

Current high-level frontend goals are listed on [Frontend Epics](https://gitlab.com/groups/gitlab-org/-/epics?label_name%5B%5D=frontend).

## Principles

[High-level guidelines](principles.md) for contributing to GitLab.

## Development Process

How we [plan and execute](development_process.md) the work on the frontend.

## Architecture

How we go about [making fundamental design decisions](architecture.md) in GitLab's frontend team
or make changes to our frontend development guidelines.

## Testing

How we write [frontend tests](../testing_guide/frontend_testing.md), run the GitLab test suite, and debug test related
issues.

## Pajamas Design System

Reusable components with technical and usage guidelines can be found in our
[Pajamas Design System](https://design.gitlab.com/).

## Design Patterns

Common JavaScript [design patterns](design_patterns.md) in GitLab's codebase.

## Vue.js Best Practices

Vue specific [design patterns and practices](vue.md).

## Vuex

[Vuex](vuex.md) specific design patterns and practices.

## Axios

[Axios](axios.md) specific practices and gotchas.

## GraphQL

How to use [GraphQL](graphql.md).

## Icons and Illustrations

How we use SVG for our [Icons and Illustrations](icons.md).

## Dependencies

General information about frontend [dependencies](dependencies.md) and how we manage them.

## Keyboard Shortcuts

How we implement [keyboard shortcuts](keyboard_shortcuts.md) that can be customized and disabled.

## Frontend FAQ

Read the [frontend's FAQ](frontend_faq.md) for common small pieces of helpful information.

## Style Guides

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

- [JavaScript](style/javascript.md). Our guide is based on
the excellent [Airbnb](https://github.com/airbnb/javascript) style guide with a few small
changes.
- [SCSS](style/scss.md): our SCSS conventions which are enforced through [`scss-lint`](https://github.com/sds/scss-lint).
- [HTML](style/html.md). Guidelines for writing HTML code consistent with the rest of the codebase.
- [Vue](style/vue.md). Guidelines and conventions for Vue code may be found here.

## [Tooling](tooling.md)

Our code is automatically formatted with [Prettier](https://prettier.io) to follow our guidelines. Read our [Tooling guide](tooling.md) for more detail.

## [Performance](performance.md)

Best practices for monitoring and maximizing frontend performance.

## [Security](security.md)

Frontend security practices.

## [Accessibility](accessibility.md)

Our accessibility standards and resources.

## [Internationalization (i18n) and Translations](../i18n/externalization.md)

Frontend internationalization support is described in [this document](../i18n/).
The [externalization part of the guide](../i18n/externalization.md) explains the helpers/methods available.
Add latest changes from gitlab-org/gitlab@master 2020-10-30 14:08:56 -04:00			`---`
			`stage: none`
			`group: unassigned`
Add latest changes from gitlab-org/gitlab@master 2020-11-26 01:09:20 -05:00			`info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments`
Add latest changes from gitlab-org/gitlab@master 2020-10-30 14:08:56 -04:00			`---`

Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`# Frontend Development Guidelines`

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

			`## Overview`

Add latest changes from gitlab-org/gitlab@master 2020-08-06 11:09:42 -04:00			`GitLab is built on top of [Ruby on Rails](https://rubyonrails.org) using [Haml](https://haml.info/) and also a JavaScript based Frontend with [Vue.js](https://vuejs.org).`
Add latest changes from gitlab-org/gitlab@master 2020-04-21 11:21:10 -04:00			`Be wary of [the limitations that come with using Hamlit](https://github.com/k0kubun/hamlit/blob/master/REFERENCE.md#limitations). We also use [SCSS](https://sass-lang.com) and plain JavaScript with`
			`modern ECMAScript standards supported through [Babel](https://babeljs.io/) and ES module support through [webpack](https://webpack.js.org/).`
Documentation: Frontend Building Checklist 2018-04-19 14:36:17 -04:00
Add latest changes from gitlab-org/gitlab@master 2020-03-09 20:08:12 -04:00			`Working with our frontend assets requires Node (v10.13.0 or greater) and Yarn`
Update FE developer and installation documentation 2019-01-10 12:35:01 -05:00			`(v1.10.0 or greater). You can find information on how to install these on our`
Add latest changes from gitlab-org/gitlab@master 2020-04-21 11:21:10 -04:00			`[installation guide](../../install/installation.md#4-node).`
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00
			`### Browser Support`

Add latest changes from gitlab-org/gitlab@master 2020-04-21 11:21:10 -04:00			`For our currently-supported browsers, see our [requirements](../../install/requirements.md#supported-web-browsers).`
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00
Add latest changes from gitlab-org/gitlab@master 2020-07-02 11:09:08 -04:00			`Use [BrowserStack](https://www.browserstack.com/) to test with our supported browsers.`
			`Sign in to BrowserStack with the credentials saved in the Engineering vault of GitLab's`
			`[shared 1Password account](https://about.gitlab.com/handbook/security/#1password-guide).`
Add BrowserStack details to Frontend Dev Guide 2019-08-12 19:40:09 -04:00
Cleanup of fe_docs Start moving back to regular fe_docs Remove Initiatives, add section to index in fe_guide Delete some no-longer-relevant parts from principles Update title - Progressive Enchancement is a browser-support term and could be confused "When to use" parts are discussed elswhere Vue & jQuery issue is no longer relevant Delete duplicate Security docs Remove empty files, move event_tracking Shuffle index sections around Remove sections on Vue & Webpack (we say same thing in prev paragraph) Remove link to Droplab docs 2019-03-14 04:19:13 -04:00			`## Initiatives`

			`Current high-level frontend goals are listed on [Frontend Epics](https://gitlab.com/groups/gitlab-org/-/epics?label_name%5B%5D=frontend).`

Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`## Principles`
Cleanup of fe_docs Start moving back to regular fe_docs Remove Initiatives, add section to index in fe_guide Delete some no-longer-relevant parts from principles Update title - Progressive Enchancement is a browser-support term and could be confused "When to use" parts are discussed elswhere Vue & jQuery issue is no longer relevant Delete duplicate Security docs Remove empty files, move event_tracking Shuffle index sections around Remove sections on Vue & Webpack (we say same thing in prev paragraph) Remove link to Droplab docs 2019-03-14 04:19:13 -04:00
Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`[High-level guidelines](principles.md) for contributing to GitLab.`
Cleanup of fe_docs Start moving back to regular fe_docs Remove Initiatives, add section to index in fe_guide Delete some no-longer-relevant parts from principles Update title - Progressive Enchancement is a browser-support term and could be confused "When to use" parts are discussed elswhere Vue & jQuery issue is no longer relevant Delete duplicate Security docs Remove empty files, move event_tracking Shuffle index sections around Remove sections on Vue & Webpack (we say same thing in prev paragraph) Remove link to Droplab docs 2019-03-14 04:19:13 -04:00
Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`## Development Process`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`How we [plan and execute](development_process.md) the work on the frontend.`
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00
Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`## Architecture`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`How we go about [making fundamental design decisions](architecture.md) in GitLab's frontend team`
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`or make changes to our frontend development guidelines.`

Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`## Testing`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`How we write [frontend tests](../testing_guide/frontend_testing.md), run the GitLab test suite, and debug test related`
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`issues.`

Add latest changes from gitlab-org/gitlab@master 2019-10-13 17:06:13 -04:00			`## Pajamas Design System`

			`Reusable components with technical and usage guidelines can be found in our`
			`[Pajamas Design System](https://design.gitlab.com/).`

Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`## Design Patterns`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`Common JavaScript [design patterns](design_patterns.md) in GitLab's codebase.`
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00
Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`## Vue.js Best Practices`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`Vue specific [design patterns and practices](vue.md).`
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00
Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`## Vuex`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`[Vuex](vuex.md) specific design patterns and practices.`
Fixes typos and adds mutations examples 2018-03-22 06:50:52 -04:00
Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`## Axios`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`[Axios](axios.md) specific practices and gotchas.`
Moves vue resource docs into a new file. Adds docs regarding handling 204 response 2017-10-23 08:07:44 -04:00
Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`## GraphQL`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`How to use [GraphQL](graphql.md).`
Added frontend GraphQL docs 2018-11-28 05:00:03 -05:00
Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`## Icons and Illustrations`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Add latest changes from gitlab-org/gitlab@master 2020-03-02 10:08:01 -05:00			`How we use SVG for our [Icons and Illustrations](icons.md).`

			`## Dependencies`

			`General information about frontend [dependencies](dependencies.md) and how we manage them.`
Resolve "Better SVG Usage in the Frontend" 2017-09-22 04:39:47 -04:00
Add latest changes from gitlab-org/gitlab@master 2020-10-12 11:08:32 -04:00			`## Keyboard Shortcuts`

			`How we implement [keyboard shortcuts](keyboard_shortcuts.md) that can be customized and disabled.`

Create frontend FAQ (documentation) 2019-04-16 11:22:05 -04:00			`## Frontend FAQ`

			`Read the [frontend's FAQ](frontend_faq.md) for common small pieces of helpful information.`

Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`## Style Guides`

Add latest changes from gitlab-org/gitlab@master 2019-11-29 13:06:24 -05:00			`See the relevant style guides for our guidelines and for information on linting:`
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00
Add latest changes from gitlab-org/gitlab@master 2019-11-29 13:06:24 -05:00			`- [JavaScript](style/javascript.md). Our guide is based on`
Add latest changes from gitlab-org/gitlab@master 2020-04-21 11:21:10 -04:00			`the excellent [Airbnb](https://github.com/airbnb/javascript) style guide with a few small`
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`changes.`
Add latest changes from gitlab-org/gitlab@master 2020-04-04 05:09:16 -04:00			- [SCSS](style/scss.md): our SCSS conventions which are enforced through [`scss-lint`](https://github.com/sds/scss-lint).
Add latest changes from gitlab-org/gitlab@master 2019-11-29 13:06:24 -05:00			`- [HTML](style/html.md). Guidelines for writing HTML code consistent with the rest of the codebase.`
			`- [Vue](style/vue.md). Guidelines and conventions for Vue code may be found here.`
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00
Add latest changes from gitlab-org/gitlab@master 2020-02-13 01:09:07 -05:00			`## [Tooling](tooling.md)`
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00
Add latest changes from gitlab-org/gitlab@master 2019-11-29 13:06:24 -05:00			`Our code is automatically formatted with [Prettier](https://prettier.io) to follow our guidelines. Read our [Tooling guide](tooling.md) for more detail.`
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00
			`## [Performance](performance.md)`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`Best practices for monitoring and maximizing frontend performance.`

			`## [Security](security.md)`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`Frontend security practices.`

			`## [Accessibility](accessibility.md)`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Creates Frontend Style guide 2017-03-22 15:30:54 -04:00			`Our accessibility standards and resources.`

Update i18n in FE docs, marking, interpolation 2017-10-24 00:16:57 -04:00			`## [Internationalization (i18n) and Translations](../i18n/externalization.md)`
Add event tracking documentation - Add link to Event tracking in FE guides 2019-02-13 09:43:19 -05:00
Update i18n in FE docs, marking, interpolation 2017-10-24 00:16:57 -04:00			`Frontend internationalization support is described in [this document](../i18n/).`
			`The [externalization part of the guide](../i18n/externalization.md) explains the helpers/methods available.`