1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
---
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/product/ux/technical-writing/#assignments
---
# Storybook
The Storybook for the `gitlab-org/gitlab` project is available on our [GitLab Pages site](https://gitlab-org.gitlab.io/gitlab/storybook/).
## Storybook in local development
Storybook dependencies and configuration are located under the `storybook/` directory.
To build and launch Storybook locally, in the root directory of the `gitlab` project:
1. Install Storybook dependencies:
```shell
yarn storybook:install
```
1. Build the Storybook site:
```shell
yarn storybook:start
```
## Adding components to Storybook
Stories can be added for any Vue component in the `gitlab` repository.
To add a story:
1. Create a new `.stories.js` file in the same directory as the Vue component.
The filename should have the same prefix as the Vue component.
```txt
vue_shared/
├─ components/
│ ├─ sidebar
│ | ├─ todo_toggle
│ | | ├─ todo_button.vue
│ │ | ├─ todo_button.stories.js
```
1. Write the story as per the [official Storybook instructions](https://storybook.js.org/docs/vue/writing-stories/introduction/)
NOTE:
Specify the `title` field of the story as the component's file path from the `javascripts/` directory, without the `/components` part.
For example, if the component is located at `app/assets/javascripts/vue_shared/components/sidebar/todo_toggle/todo_button.vue`,
specify the story `title` as `vue_shared/sidebar/todo_toggle/todo_button`.
If the component is located in the `ee/` directory, make sure to prefix the story's title with `ee/` as well.
This will ensure the Storybook navigation maps closely to our internal directory structure.
## Using GitLab REST and GraphQL APIs
You can write stories for components that use either GitLab’s [REST](../../api/rest/index.md) or
[GraphQL](../../api/graphql/index.md) APIs.
### Set up API access token and GitLab instance URL
To add a story with API access:
1. Create a [personal access token](../../user/profile/personal_access_tokens.md) in your GitLab instance.
NOTE:
If you test against `gitlab.com`, make sure to use a token with `read_api` if possible and to make the token short-lived.
1. Create an `.env` file in the `storybook` directory. Use the `storybook/.env.template` file as
a starting point.
1. Set the `API_ACCESS_TOKEN` variable to the access token that you created.
1. Set the `GITLAB_URL` variable to the GitLab instance’s domain URL, for example: `http://gdk.test:3000`.
1. Start or restart your storybook.
You can also use the GitLab API Access panel in the Storybook UI to set the GitLab instance URL and access token.
### Set up API access in your stories
You should apply the `withGitLabAPIAccess` decorator to the stories that will consume GitLab’s APIs. This decorator
will display a badge indicating that the story won't work without providing the API access parameters:
```javascript
import { withGitLabAPIAccess } from 'storybook_addons/gitlab_api_access';
import Api from '~/api';
import { ContentEditor } from './index';
export default {
component: ContentEditor,
title: 'ce/content_editor/content_editor',
decorators: [withGitLabAPIAccess],
};
```
#### Using REST API
The Storybook sets up `~/lib/utils/axios_utils` in `storybook/config/preview.js`. Components that use the REST API
should work out of the box as long as you provide a valid GitLab instance URL and access token.
#### Using GraphQL
To write a story for a component that uses the GraphQL API, use the `createVueApollo` method provided in
the Story context.
```javascript
import Vue from 'vue';
import VueApollo from 'vue-apollo';
import { withGitLabAPIAccess } from 'storybook_addons/gitlab_api_access';
import WorkspacesList from './list.vue';
Vue.use(VueApollo);
const Template = (_, { argTypes, createVueApollo }) => {
return {
components: { WorkspacesList },
apolloProvider: createVueApollo(),
provide: {
emptyStateSvgPath: '',
},
props: Object.keys(argTypes),
template: '<workspaces-list />',
};
};
export default {
component: WorkspacesList,
title: 'ee/remote_development/workspaces_list',
decorators: [withGitLabAPIAccess],
};
export const Default = Template.bind({});
Default.args = {};
```
|
