From f80c75cf7e652460b0a1958407a2524fb57bdee0 Mon Sep 17 00:00:00 2001
From: Mark Florian <mflorian@gitlab.com>
Date: Wed, 10 Jul 2019 12:24:57 +0800
Subject: Document how to access feature flags in Vue

Originated from this [discussion][1].

[1]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/14531#note_188376382
---
 doc/development/fe_guide/vue.md              | 43 ++++++++++++++++++++++++++++
 doc/development/feature_flags/development.md |  3 ++
 2 files changed, 46 insertions(+)

diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md
index 6c7572352ec..ab1309d05ad 100644
--- a/doc/development/fe_guide/vue.md
+++ b/doc/development/fe_guide/vue.md
@@ -103,6 +103,49 @@ document.addEventListener('DOMContentLoaded', () => new Vue({
 }));
 ```
 
+#### Accessing feature flags
+
+Use Vue's [provide/inject](https://vuejs.org/v2/api/#provide-inject) mechanism
+to make feature flags available to any descendant components in a Vue
+application:
+
+```javascript
+// application entry point
+document.addEventListener('DOMContentLoaded', () => new Vue({
+  el: '.js-vue-app',
+  provide: {
+    aFeatureFlag: gon.features.aFeatureFlag,
+  },
+  render(createElement) {
+    return createElement('my-component');
+  },
+}));
+
+// An arbitrary descendant component
+export default {
+  ...
+  inject: {
+    aFeatureFlag: {
+      from: 'aFeatureFlag',
+      default: false,
+    },
+  },
+  ...
+}
+```
+
+This approach has several benefits:
+
+- Arbitrarily deeply nested components can opt-in and access the flag without
+  intermediate components being aware of it (c.f. passing the flag down via
+  props).
+- Components can use a different local name for the flag if necessary.
+- A default value can be declared in case the flag is not provided.
+- Good testability, since the flag can be provided to `mount`/`shallowMount`
+  from `vue-test-utils` as easily as a prop.
+- No need to access a global variable, except in the application's
+  [entry point](#accessing-the-gl-object).
+
 ### A folder for Components
 
 This folder holds all components that are specific of this new feature.
diff --git a/doc/development/feature_flags/development.md b/doc/development/feature_flags/development.md
index 98773026122..dceacc2f407 100644
--- a/doc/development/feature_flags/development.md
+++ b/doc/development/feature_flags/development.md
@@ -109,6 +109,9 @@ if ( gon.features.vimBindings ) {
 The name of the feature flag in JavaScript will always be camelCased, meaning
 that checking for `gon.features.vim_bindings` would not work.
 
+See the [Vue guide](../fe_guide/vue.md#accessing-feature-flags) for details about
+how to access feature flags in a Vue application.
+
 ### Specs
 
 In the test environment `Feature.enabled?` is stubbed to always respond to `true`,
-- 
cgit v1.2.1