{"componentChunkName":"component---src-pages-tutorial-vue-step-1-mdx","path":"/tutorial/vue/step-1/","result":{"pageContext":{"isCreatedByStatefulCreatePages":true,"frontmatter":{"title":"1. Installing Carbon","description":"Welcome to Carbon! This tutorial will guide you in creating a Vue app with the Carbon Design System.","internal":false,"tabs":["Overview","Step 1","Step 2","Step 3","Step 4","Step 5","Wrapping up"]},"relativePagePath":"/tutorial/vue/step-1.mdx","titleType":"prepend","MdxNode":{"id":"4ac50a83-d9ae-5388-9216-4f8b7d5f0155","children":[],"parent":"14cd8387-df22-5144-bb30-e1b215250932","internal":{"content":"---\ntitle: 1. Installing Carbon\ndescription: Welcome to Carbon! This tutorial will guide you in creating a Vue app with the Carbon Design System.\ninternal: false\ntabs:\n ['Overview', 'Step 1', 'Step 2', 'Step 3', 'Step 4', 'Step 5', 'Wrapping up']\n---\n\n### Starting with our Vue CLI generated app, let's install Carbon and begin using Carbon components. By the end you will have a Vue app that uses the UI Shell to navigate between pages.\n\n\n\nFork, clone and branch\nBuild and start\nInstall Carbon\nOther dependencies\nAdd UI Shell\nCreate pages\nAdd routing\nSubmit pull request\n\n\n\n## Preview\n\nA [preview](https://vue-step-2--carbon-tutorial-vue.netlify.com) of what you will build:\n\n\n\n## Fork, clone and branch\n\nThis tutorial has an accompanying GitHub repository called [carbon-tutorial-vue](https://github.com/carbon-design-system/carbon-tutorial-vue) that we'll use as a starting point for each step.\n\n### Fork\n\nTo begin, fork [carbon-tutorial-vue](https://github.com/carbon-design-system/carbon-tutorial-vue) using your GitHub account.\n\n### Clone\n\nGo to your forked repository, copy the SSH or HTTPS URL and in your terminal run the two commands to get the repository in your local file system and enter that directory.\n\n```bash\n$ git clone [your fork SSH/HTTPS]\n$ cd carbon-tutorial-vue\n```\n\n### Add upstream remote\n\nAdd a remote called `upstream` so we can eventually submit a pull request once you have completed this tutorial step.\n\n```bash\n$ git remote add upstream git@github.com:carbon-design-system/carbon-tutorial-vue.git\n```\n\nOr, if you prefer to use HTTPS instead of SSH with your remotes:\n\n```bash\n$ git remote add upstream https://github.com/carbon-design-system/carbon-tutorial-vue.git\n```\n\nVerify that your forked repository remotes are correct:\n\n```bash\n$ git remote -v\n```\n\nYour terminal should output something like this:\n\n```bash\norigin\t[your forked repo] (fetch)\norigin\t[your forked repo] (push)\nupstream\tgit@github.com:carbon-design-system/carbon-tutorial-vue.git (fetch)\nupstream\tgit@github.com:carbon-design-system/carbon-tutorial-vue.git (push)\n```\n\n### Branch\n\nNow that we have our repository set up, let's check out the branch for this tutorial step's starting point. Run the two commands:\n\n```bash\n$ git fetch upstream\n$ git checkout -b vue-step-1 upstream/vue-step-1\n```\n\n## Build and start\n\nWe have the repository forked to your GitHub account, cloned down to your machine, and the starting branch checked out. Next, install the Vue app's dependencies with:\n\n```bash\n$ yarn\n```\n\nAfter the dependencies are installed, you can start the app with:\n\n```bash\n$ yarn serve\n```\n\nYour default browser should open up with an empty page that says: `Hello Carbon! Well, not quite yet. This is the starting point for the Carbon tutorial.`\n\nOK. So we made a small change to the Vue CLI geneated app replacing the HelloWorld component and replaced it with our own message and swapped out the facicon.\n\n## Install Carbon\n\nEven though we installed existing dependencies, we've yet to install the Carbon packages.\n\n- `carbon-components` - component styles\n- `@carbon/vue` - Vue components\n- `@carbon/icons-vue` - Vue icons\n\nStop your development server with `CTRL-C` and install Carbon dependencies with:\n\n```bash\n$ yarn add carbon-components @carbon/vue @carbon/icons-vue\n```\n\n## Other dependencies\n\nIf you check out the file `package.json`, you'll notice a few dependencies beyond those listed above. These were installed as part of the project creation using the Vue CLI. These include:\n\n- vue-router: Used to make routing in Vue apps simpler\n- @vue/cli-plugin-babel: To ensure we produce well supported code.\n- @vue/cli-plugin-eslint: To allow us to catch potential errors.\n- @vue/cli-plugin-unit-jest: To allow us to unit test our code.\n- node-sass: To allow us to use the sass css precompiler.\n\nNOTE: We could have installed these seperately but using the CLI to set this up for us ensures a good base config for these dependencies.\n\nTo avoid having to add the `~` prefix when importing SCSS files from `node_modules`, create a `.env` file at the project root that contains:\n\n##### .env\n\n```bash\nSASS_PATH=\"node_modules\"\n```\n\nFor the Windows operating system, use:\n\n##### .env\n\n```bash\nSASS_PATH=./node_modules\n```\n\nThen, start the app again. If your app's currently running, you'll need to restart it for the new environment variable to be used.\n\n```bash\n$ yarn serve\n```\n\nThe app looks as it did before. Next, let's add Carbon styling.\n\n### Import carbon-component styles\n\nIn the `src` directory, create a sub-directory `styles` and add a new file `_carbon.scss` to it. Then in `App.vue` edit the style tag to import it.\n\n#### src/App.vue\n\n\n```scss\n\n```\n\n\nIn `styles/_carbon.scss`, import the Carbon styles by adding the following at the top of the file:\n\n##### src/styles/\\_carbon.scss\n\n```scss\n@import 'carbon-components/scss/globals/scss/styles';\n```\n\nThis will take a moment for the Sass to compile. Once compiled, you'll notice that the Carbon base styling is applied (IBM Plex Sans font family, font size, weight, colors, etc.)\n\nBecause any change to `_carbon.scss` will re-compile all of the Carbon Sass, avoid making changes here unless instructed to do so. it is better to make them in the component files or a seperate file if needed.\n\nNext we'll create a Carbon `Button` to test that our dependencies are working properly.\n\n#### src/main.js\n\nAfter the other imports in main.js and before the Vue instance is created add the following.\n\n\n```javascript\nimport CarbonComponentsVue from \"@carbon/vue\";\nVue.use(CarbonComponentsVue);\n```\n\n\nThis is a quick way to pull in all @carbon/vue components and register them for use in your project. Individual components can be imported to a project or component.\n\ne.g. Instead of modifying src/main.js we could have added the following to src/App.vue:\n\n##### src/App.vue\n\n```javascript\n\n```\n\nSee the Carbon Vue Components [documentation](https://github.com/carbon-design-system/carbon-components-vue/blob/master/packages/core/README.md#using-the-components-directly-or-individually) for other ways to load components from @carbon/vue components.\n\nIn this tutorial we will stick to importing all of the components at once so we can focus on our use of @carbon/vue.\n\nNow open the `App.vue` component and replace:\n\n##### src/App.vue\n\n\n```html\n Hello Carbon! Well, not quite yet. This is the starting point for the Carbon tutorial.\n```\n\n\nwith:\n\n##### src/App.vue\n\n\n```html\nButton\n```\n\nor\n\n```html\nButton\n```\n\n\nCongratulations, you've imported your first component! You should see a Carbon styled button on the page.\n\nNOTE: In this tutorial you can use either tag format. The [Vue style guide](https://vuejs.org/v2/style-guide/) recommend sticking to either Pascal or kebab case. The examples from here will use Pascal case for file and component names with kebab case in the HTML.\n\n## Add UI Shell\n\nNext we're going to create a Vue component called `TutorialHeader` to use with the UI Shell Carbon component. Create a new directory `src/components`. In the `src/components` directory, create `TutorialHeader` directory. Create the following files inside `src/components/TutorialHeader`:\n\n```bash\nsrc/components/TutorialHeader\n├──index.js\n└──TutorialHeader.vue\n```\n\n### Import and export the header\n\nIn `src/components/TutorialHeader/index.js`, import and export our `TutorialHeader` component like so:\n\n##### src/components/TutorialHeader/index.js\n\n```javascript\nimport TutorialHeader from './TutorialHeader';\nexport default TutorialHeader;\n```\n\n_Note: This index.js files import/export is simply a convenience to shorten the path used to import the component and potentially import multiple components from one folder. The folder also provides us a handy location to add tests or documentation for the component._\n\n_Note: We could have simply created a file src/components/TutorialHeader.vue without the above benefits._\n\n#### Lazyness - VSCode users only\n\nIf you are using VSCode then you might want to add the following snippet which will when you type 'index' generate an index file for you based on the folder name.\n\n##### javascript.json\n\n```json\n \"index-file\": {\n \"prefix\": \"index\",\n \"body\": [\n \"import ${TM_DIRECTORY/.*[\\\\/]//gm} from './${TM_DIRECTORY/.*[\\\\/]//gm}';\",\n \"export { \",\n \"\\t${TM_DIRECTORY/.*[\\\\/]//gm},\",\n \"};\",\n \"export default ${TM_DIRECTORY/.*[\\\\/]//gm}\",\n \"\"\n ],\n \"description\": \"Index file\"\n }\n```\n\nYou can also use the following to create a skeleton component. To use this one, start typing the word template in your template file and it will generate a file, making assumptions based on the component file name.\n\n##### vue.json\n\n```json\n \"Vue_Component\": {\n \"prefix\": \"template\",\n \"body\": [\n \"\",\n \"\\t$0\",\n \"\",\n \"\",\n \"\",\n \"\",\n \"\",\n \"\"\n ],\n \"description\": \"Single file template\"\n }\n```\n\nOK, back to using Carbon components. Let's make use of our Carbon UI Shell components in `TutorialHeader.vue`. Set up the file like so:\n\n##### src/components/TutorialHeader/TutorialHeader.vue\n\n```html\n\n \n Skip to content\n\n Carbon Tutorial\n\n \n Repositories\n \n\n \n \n\n```\n\n_Note: you can find a description of the different components used in UI Shell in our [carbon-componets-vue](http://vue.carbondesignsystem.com/?path=/story/components-cvuishell-header) package._\n\n_Note: When creating navigation headers, it's important to have a_ `Skip to content` _link so keyboard users can skip the navigation items and go straight to the main content._\n\n_Note: It's important that the_ `TutorialHeader` has the Carbon* `CvHeader` \\_as it's containing element, as we'll later be rendering* `TutorialHeader` _in_ `App.vue` _as a preceeding sibling of_ `Content`_, another UI Shell component. Those components need to live one after another for the UI Shell to properly render._\n\n### Import icons\n\nNow let's import the icons from our `@carbon/icons-vue` elements package. After the closing template tag in the `TutorialHeader.vue` file, we need to import each individual icon we will use.\n\n##### src/components/TutorialHeader/TutorialHeader.vue\n\n\n```javascript\n\n```\n\n\n_Note: We've given our component a name here as part of the default export. This is optional in Vue but very useful in the [Vue developer tools](https://github.com/vuejs/vue-devtools)._\n\nThen we need to add content to the `header-global` slot where we will use our icons. These represent actions in the header a user can make. Replace:\n\n##### src/components/TutorialHeader/TutorialHeader.vue\n\n```html\n\n```\n\nWith:\n\n##### src/components/TutorialHeader/TutorialHeader.vue\n\n```html\n\n \n \n \n \n \n \n \n \n \n\n```\n\n### Render the header\n\nNext we'll render our UI Shell by importing our `TutorialHeader` component and `CvContent` into `App.vue`. Add a script tag if you don't have one, then update it as follows:\n\n##### src/App.vue\n\n```javascript\n\n```\n\nIn addition to importing the `TutorialHeader` component, we have also declared it for use in our template by adding it to the `components` property of our component.\n\nAs our template currently just contains a `Button` it is still not rendering anything more interesting so let's update that to include our imported components. This should look like the following:\n\n##### src/App.vue\n\n```html\n\n \n \n \n Button\n \n
\n\n```\n\nYou should now see a styled UI Shell header and a button below it.\n\n_Note: We've also sneaked in use of `CvContent` which needs to follow `CvHeader` to ensure the correct formatting. We could have included it as part of a shell component with TutorialHeader but have chosen not to in this case._\n\n## Create pages\n\nNext thing we need to do is create the files for our views.\n\nSince our app will have two pages, we'll create two folders in `src/views`. Clear out the files currently in the views folder and add the following folders.\n\n```bash\nsrc/views\n├── LandingPage\n└── RepoPage\n```\n\nCreate the following files in the `LandingPage` folder:\n\n```bash\nsrc/view/LandingPage\n├── index.js\n└── LandingPage.vue\n```\n\nCreate the following files in the `RepoPage` folder:\n\n```bash\nsrc/view/RepoPage\n├── index.js\n└── RepoPage.vue\n```\n\n### Import and export content pages\n\nStarting with `LandingPage`, just like with our header, we need to export the component in `src/view/LandingPage/index.js` by adding:\n\n##### src/view/LandingPage/index.js\n\n```javascript\nimport LandingPage from './LandingPage';\nexport default LandingPage;\n```\n\nNext in `LandingPage.vue` we'll create our component.\n\n##### src/view/LandingPage/LandingPage.vue\n\n```html\n\n LANDING PAGE
\n\n```\n\nWe'll repeat this process with `RepoPage`.\n\nIn `src/view/RepoPage/index.js`, import and export the `RepoPage` component like so:\n\n##### src/view/RepoPage/index.js\n\n```javascript\nimport RepoPage from './RepoPage';\nexport default RepoPage;\n```\n\nThen in `RepoPage.vue` create the component.\n\n##### src/view/RepoPage/RepoPage.vue\n\n```html\n\n REPO PAGE
\n\n```\n\nAwesome! We've just created our content pages. Next thing we need to do is render them with our router.\n\n## Add routing\n\nLucky for you, as part of the Vue CLI project set up we added vue-router. This created the views folder and also added, `src/router.js` and imported that into `src/main.js` for us.\n\n#### src/router.js\n\nWe need to adjust it by replacing the contents of `src/router.js` with:\n\n```javascript\nimport Vue from 'vue';\nimport Router from 'vue-router';\nimport LandingPage from './views/LandingPage';\n\nVue.use(Router);\n\nexport default new Router({\n routes: [\n {\n path: '/',\n name: 'landing-page',\n component: LandingPage,\n },\n {\n path: '/repos',\n name: 'repo-page',\n // route level code-splitting\n // this generates a separate chunk (repo-page.[hash].js) for this route\n // which is lazy-loaded when the route is visited.\n component: () =>\n import(/* webpackChunkName: \"repo-page\" */ './views/RepoPage'),\n },\n ],\n});\n```\n\n_Note: The landing page is loaded immediately, with the RepoPage loaded only once needed. This is one simple way to create webpackChunks and is the default suggestion from the CLI plugin for vue-router._\n\nIf you click on `Repositories` and then on `IBM Carbon Tutorial` you'll notice a flicker as we hop from one page to another. We can fix this by using vue-router to manage our views.\n\nNext we need to update `src/App.vue` to render these views.\n\nIn the template section remove the `` and replace it with `` as follows\n\n#### src/App.vue\n\n```html\n\n \n\n```\n\nAfter that we need to do a couple quick fixes to the UI Shell to have it work with the vue-router.\n\n##### src/components/TutorialHeader/TutorialHeader.vue\n\nIn `src/components/TuturialHeader/TutorialHeader.vue` simply replace the `href` attributes used in the `cv-header-name` and `cv-header-menu-item` components with `to`. @carbon/vue will under the covers switch from use of an `a` tag to `router-link`.\n\n```html\nCarbon Tutorial\n```\n\nand\n\n```html\nRepositories\n```\n\nYou should now have a working header that routes to different pages without full page reload!\n\n## Submit pull request\n\nWe're going to submit a pull request to verify completion of this tutorial step and demonstrate a couple of related concepts.\n\n### Continuous integration (CI) check\n\nWe have a `ci-check` script defined in `package.json` that verifies file formatting for files that have been touched since the last Git commit with a tool called [Prettier](https://prettier.io). You'd typically also have that script run your test suite as part of your CI build. Go ahead and make sure everything looks good with:\n\n```bash\n$ yarn ci-check\n```\n\n_Note: If the_ `ci-check` _is giving an error, it's likely that some of your source files are not properly formatted. This could happen if your text editor isn't formatting with Prettier on save._\n\n\n\n\n### Git commit and push\n\nBefore we can create a pull request, stage and commit all of your changes:\n\n```bash\n$ git add --all && git commit -m \"feat(tutorial): complete step 1\"\n```\n\n\n\n\nThen, push to your repository:\n\n```bash\n$ git push origin vue-step-1\n```\n\n_Note: If your Git remote protocol is HTTPS instead of SSH, you may be prompted to authenticate with GitHub when you push changes. If your GitHub account has two-factor authentication enabled, we recommend that you follow these instructions to [create a personal access token for the command line](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line). That lets you use your token instead of password when performing Git operations over HTTPS._\n\n_Note: If you receive a_ `non-fast-forward` _error, it's likely that your forked repository is behind the original repository and needs updated. This can happen if the tutorial was updated after you began working on it. To fix, run_ `git pull upstream vue-step-1` _to merge the changes into your branch, then you can try pushing again. Or, you can [manually merge](https://help.github.com/en/articles/syncing-a-fork) in the upstream changes._\n\n### Pull request (PR)\n\nFinally, visit [carbon-tutorial-vue](https://github.com/carbon-design-system/carbon-tutorial-vue) to \"Compare & create pull request\". In doing so, make sure that you are comparing your repository's `vue-step-1` branch into `base: vue-step-1`. Take notice of the [Netlify](https://www.netlify.com) bot that deploys a preview of your PR every time that you push new commits. These previews can be shared and viewed by anybody to assist the PR review process.\n\n_Note: Expect your tutorial step PRs to be reviewed by the Carbon team but not merged. We'll close your PR so we can keep the repository's remote branches pristine and ready for the next person!_\n","type":"Mdx","contentDigest":"1657697c134bbd8170f4f347f4cd71d6","counter":1511,"owner":"gatsby-plugin-mdx"},"frontmatter":{"title":"1. Installing Carbon","description":"Welcome to Carbon! This tutorial will guide you in creating a Vue app with the Carbon Design System.","internal":false,"tabs":["Overview","Step 1","Step 2","Step 3","Step 4","Step 5","Wrapping up"]},"exports":{},"rawBody":"---\ntitle: 1. Installing Carbon\ndescription: Welcome to Carbon! This tutorial will guide you in creating a Vue app with the Carbon Design System.\ninternal: false\ntabs:\n ['Overview', 'Step 1', 'Step 2', 'Step 3', 'Step 4', 'Step 5', 'Wrapping up']\n---\n\n### Starting with our Vue CLI generated app, let's install Carbon and begin using Carbon components. By the end you will have a Vue app that uses the UI Shell to navigate between pages.\n\n\n\nFork, clone and branch\nBuild and start\nInstall Carbon\nOther dependencies\nAdd UI Shell\nCreate pages\nAdd routing\nSubmit pull request\n\n\n\n## Preview\n\nA [preview](https://vue-step-2--carbon-tutorial-vue.netlify.com) of what you will build:\n\n\n\n## Fork, clone and branch\n\nThis tutorial has an accompanying GitHub repository called [carbon-tutorial-vue](https://github.com/carbon-design-system/carbon-tutorial-vue) that we'll use as a starting point for each step.\n\n### Fork\n\nTo begin, fork [carbon-tutorial-vue](https://github.com/carbon-design-system/carbon-tutorial-vue) using your GitHub account.\n\n### Clone\n\nGo to your forked repository, copy the SSH or HTTPS URL and in your terminal run the two commands to get the repository in your local file system and enter that directory.\n\n```bash\n$ git clone [your fork SSH/HTTPS]\n$ cd carbon-tutorial-vue\n```\n\n### Add upstream remote\n\nAdd a remote called `upstream` so we can eventually submit a pull request once you have completed this tutorial step.\n\n```bash\n$ git remote add upstream git@github.com:carbon-design-system/carbon-tutorial-vue.git\n```\n\nOr, if you prefer to use HTTPS instead of SSH with your remotes:\n\n```bash\n$ git remote add upstream https://github.com/carbon-design-system/carbon-tutorial-vue.git\n```\n\nVerify that your forked repository remotes are correct:\n\n```bash\n$ git remote -v\n```\n\nYour terminal should output something like this:\n\n```bash\norigin\t[your forked repo] (fetch)\norigin\t[your forked repo] (push)\nupstream\tgit@github.com:carbon-design-system/carbon-tutorial-vue.git (fetch)\nupstream\tgit@github.com:carbon-design-system/carbon-tutorial-vue.git (push)\n```\n\n### Branch\n\nNow that we have our repository set up, let's check out the branch for this tutorial step's starting point. Run the two commands:\n\n```bash\n$ git fetch upstream\n$ git checkout -b vue-step-1 upstream/vue-step-1\n```\n\n## Build and start\n\nWe have the repository forked to your GitHub account, cloned down to your machine, and the starting branch checked out. Next, install the Vue app's dependencies with:\n\n```bash\n$ yarn\n```\n\nAfter the dependencies are installed, you can start the app with:\n\n```bash\n$ yarn serve\n```\n\nYour default browser should open up with an empty page that says: `Hello Carbon! Well, not quite yet. This is the starting point for the Carbon tutorial.`\n\nOK. So we made a small change to the Vue CLI geneated app replacing the HelloWorld component and replaced it with our own message and swapped out the facicon.\n\n## Install Carbon\n\nEven though we installed existing dependencies, we've yet to install the Carbon packages.\n\n- `carbon-components` - component styles\n- `@carbon/vue` - Vue components\n- `@carbon/icons-vue` - Vue icons\n\nStop your development server with `CTRL-C` and install Carbon dependencies with:\n\n```bash\n$ yarn add carbon-components @carbon/vue @carbon/icons-vue\n```\n\n## Other dependencies\n\nIf you check out the file `package.json`, you'll notice a few dependencies beyond those listed above. These were installed as part of the project creation using the Vue CLI. These include:\n\n- vue-router: Used to make routing in Vue apps simpler\n- @vue/cli-plugin-babel: To ensure we produce well supported code.\n- @vue/cli-plugin-eslint: To allow us to catch potential errors.\n- @vue/cli-plugin-unit-jest: To allow us to unit test our code.\n- node-sass: To allow us to use the sass css precompiler.\n\nNOTE: We could have installed these seperately but using the CLI to set this up for us ensures a good base config for these dependencies.\n\nTo avoid having to add the `~` prefix when importing SCSS files from `node_modules`, create a `.env` file at the project root that contains:\n\n##### .env\n\n```bash\nSASS_PATH=\"node_modules\"\n```\n\nFor the Windows operating system, use:\n\n##### .env\n\n```bash\nSASS_PATH=./node_modules\n```\n\nThen, start the app again. If your app's currently running, you'll need to restart it for the new environment variable to be used.\n\n```bash\n$ yarn serve\n```\n\nThe app looks as it did before. Next, let's add Carbon styling.\n\n### Import carbon-component styles\n\nIn the `src` directory, create a sub-directory `styles` and add a new file `_carbon.scss` to it. Then in `App.vue` edit the style tag to import it.\n\n#### src/App.vue\n\n\n```scss\n\n```\n\n\nIn `styles/_carbon.scss`, import the Carbon styles by adding the following at the top of the file:\n\n##### src/styles/\\_carbon.scss\n\n```scss\n@import 'carbon-components/scss/globals/scss/styles';\n```\n\nThis will take a moment for the Sass to compile. Once compiled, you'll notice that the Carbon base styling is applied (IBM Plex Sans font family, font size, weight, colors, etc.)\n\nBecause any change to `_carbon.scss` will re-compile all of the Carbon Sass, avoid making changes here unless instructed to do so. it is better to make them in the component files or a seperate file if needed.\n\nNext we'll create a Carbon `Button` to test that our dependencies are working properly.\n\n#### src/main.js\n\nAfter the other imports in main.js and before the Vue instance is created add the following.\n\n\n```javascript\nimport CarbonComponentsVue from \"@carbon/vue\";\nVue.use(CarbonComponentsVue);\n```\n\n\nThis is a quick way to pull in all @carbon/vue components and register them for use in your project. Individual components can be imported to a project or component.\n\ne.g. Instead of modifying src/main.js we could have added the following to src/App.vue:\n\n##### src/App.vue\n\n```javascript\n\n```\n\nSee the Carbon Vue Components [documentation](https://github.com/carbon-design-system/carbon-components-vue/blob/master/packages/core/README.md#using-the-components-directly-or-individually) for other ways to load components from @carbon/vue components.\n\nIn this tutorial we will stick to importing all of the components at once so we can focus on our use of @carbon/vue.\n\nNow open the `App.vue` component and replace:\n\n##### src/App.vue\n\n\n```html\n Hello Carbon! Well, not quite yet. This is the starting point for the Carbon tutorial.\n```\n\n\nwith:\n\n##### src/App.vue\n\n\n```html\nButton\n```\n\nor\n\n```html\nButton\n```\n\n\nCongratulations, you've imported your first component! You should see a Carbon styled button on the page.\n\nNOTE: In this tutorial you can use either tag format. The [Vue style guide](https://vuejs.org/v2/style-guide/) recommend sticking to either Pascal or kebab case. The examples from here will use Pascal case for file and component names with kebab case in the HTML.\n\n## Add UI Shell\n\nNext we're going to create a Vue component called `TutorialHeader` to use with the UI Shell Carbon component. Create a new directory `src/components`. In the `src/components` directory, create `TutorialHeader` directory. Create the following files inside `src/components/TutorialHeader`:\n\n```bash\nsrc/components/TutorialHeader\n├──index.js\n└──TutorialHeader.vue\n```\n\n### Import and export the header\n\nIn `src/components/TutorialHeader/index.js`, import and export our `TutorialHeader` component like so:\n\n##### src/components/TutorialHeader/index.js\n\n```javascript\nimport TutorialHeader from './TutorialHeader';\nexport default TutorialHeader;\n```\n\n_Note: This index.js files import/export is simply a convenience to shorten the path used to import the component and potentially import multiple components from one folder. The folder also provides us a handy location to add tests or documentation for the component._\n\n_Note: We could have simply created a file src/components/TutorialHeader.vue without the above benefits._\n\n#### Lazyness - VSCode users only\n\nIf you are using VSCode then you might want to add the following snippet which will when you type 'index' generate an index file for you based on the folder name.\n\n##### javascript.json\n\n```json\n \"index-file\": {\n \"prefix\": \"index\",\n \"body\": [\n \"import ${TM_DIRECTORY/.*[\\\\/]//gm} from './${TM_DIRECTORY/.*[\\\\/]//gm}';\",\n \"export { \",\n \"\\t${TM_DIRECTORY/.*[\\\\/]//gm},\",\n \"};\",\n \"export default ${TM_DIRECTORY/.*[\\\\/]//gm}\",\n \"\"\n ],\n \"description\": \"Index file\"\n }\n```\n\nYou can also use the following to create a skeleton component. To use this one, start typing the word template in your template file and it will generate a file, making assumptions based on the component file name.\n\n##### vue.json\n\n```json\n \"Vue_Component\": {\n \"prefix\": \"template\",\n \"body\": [\n \"\",\n \"\\t$0\",\n \"\",\n \"\",\n \"\",\n \"\",\n \"\",\n \"\"\n ],\n \"description\": \"Single file template\"\n }\n```\n\nOK, back to using Carbon components. Let's make use of our Carbon UI Shell components in `TutorialHeader.vue`. Set up the file like so:\n\n##### src/components/TutorialHeader/TutorialHeader.vue\n\n```html\n\n \n Skip to content\n\n Carbon Tutorial\n\n \n Repositories\n \n\n \n \n\n```\n\n_Note: you can find a description of the different components used in UI Shell in our [carbon-componets-vue](http://vue.carbondesignsystem.com/?path=/story/components-cvuishell-header) package._\n\n_Note: When creating navigation headers, it's important to have a_ `Skip to content` _link so keyboard users can skip the navigation items and go straight to the main content._\n\n_Note: It's important that the_ `TutorialHeader` has the Carbon* `CvHeader` \\_as it's containing element, as we'll later be rendering* `TutorialHeader` _in_ `App.vue` _as a preceeding sibling of_ `Content`_, another UI Shell component. Those components need to live one after another for the UI Shell to properly render._\n\n### Import icons\n\nNow let's import the icons from our `@carbon/icons-vue` elements package. After the closing template tag in the `TutorialHeader.vue` file, we need to import each individual icon we will use.\n\n##### src/components/TutorialHeader/TutorialHeader.vue\n\n\n```javascript\n\n```\n\n\n_Note: We've given our component a name here as part of the default export. This is optional in Vue but very useful in the [Vue developer tools](https://github.com/vuejs/vue-devtools)._\n\nThen we need to add content to the `header-global` slot where we will use our icons. These represent actions in the header a user can make. Replace:\n\n##### src/components/TutorialHeader/TutorialHeader.vue\n\n```html\n\n```\n\nWith:\n\n##### src/components/TutorialHeader/TutorialHeader.vue\n\n```html\n\n \n \n \n \n \n \n \n \n \n\n```\n\n### Render the header\n\nNext we'll render our UI Shell by importing our `TutorialHeader` component and `CvContent` into `App.vue`. Add a script tag if you don't have one, then update it as follows:\n\n##### src/App.vue\n\n```javascript\n\n```\n\nIn addition to importing the `TutorialHeader` component, we have also declared it for use in our template by adding it to the `components` property of our component.\n\nAs our template currently just contains a `Button` it is still not rendering anything more interesting so let's update that to include our imported components. This should look like the following:\n\n##### src/App.vue\n\n```html\n\n \n \n \n Button\n \n
\n\n```\n\nYou should now see a styled UI Shell header and a button below it.\n\n_Note: We've also sneaked in use of `CvContent` which needs to follow `CvHeader` to ensure the correct formatting. We could have included it as part of a shell component with TutorialHeader but have chosen not to in this case._\n\n## Create pages\n\nNext thing we need to do is create the files for our views.\n\nSince our app will have two pages, we'll create two folders in `src/views`. Clear out the files currently in the views folder and add the following folders.\n\n```bash\nsrc/views\n├── LandingPage\n└── RepoPage\n```\n\nCreate the following files in the `LandingPage` folder:\n\n```bash\nsrc/view/LandingPage\n├── index.js\n└── LandingPage.vue\n```\n\nCreate the following files in the `RepoPage` folder:\n\n```bash\nsrc/view/RepoPage\n├── index.js\n└── RepoPage.vue\n```\n\n### Import and export content pages\n\nStarting with `LandingPage`, just like with our header, we need to export the component in `src/view/LandingPage/index.js` by adding:\n\n##### src/view/LandingPage/index.js\n\n```javascript\nimport LandingPage from './LandingPage';\nexport default LandingPage;\n```\n\nNext in `LandingPage.vue` we'll create our component.\n\n##### src/view/LandingPage/LandingPage.vue\n\n```html\n\n LANDING PAGE
\n\n```\n\nWe'll repeat this process with `RepoPage`.\n\nIn `src/view/RepoPage/index.js`, import and export the `RepoPage` component like so:\n\n##### src/view/RepoPage/index.js\n\n```javascript\nimport RepoPage from './RepoPage';\nexport default RepoPage;\n```\n\nThen in `RepoPage.vue` create the component.\n\n##### src/view/RepoPage/RepoPage.vue\n\n```html\n\n REPO PAGE
\n\n```\n\nAwesome! We've just created our content pages. Next thing we need to do is render them with our router.\n\n## Add routing\n\nLucky for you, as part of the Vue CLI project set up we added vue-router. This created the views folder and also added, `src/router.js` and imported that into `src/main.js` for us.\n\n#### src/router.js\n\nWe need to adjust it by replacing the contents of `src/router.js` with:\n\n```javascript\nimport Vue from 'vue';\nimport Router from 'vue-router';\nimport LandingPage from './views/LandingPage';\n\nVue.use(Router);\n\nexport default new Router({\n routes: [\n {\n path: '/',\n name: 'landing-page',\n component: LandingPage,\n },\n {\n path: '/repos',\n name: 'repo-page',\n // route level code-splitting\n // this generates a separate chunk (repo-page.[hash].js) for this route\n // which is lazy-loaded when the route is visited.\n component: () =>\n import(/* webpackChunkName: \"repo-page\" */ './views/RepoPage'),\n },\n ],\n});\n```\n\n_Note: The landing page is loaded immediately, with the RepoPage loaded only once needed. This is one simple way to create webpackChunks and is the default suggestion from the CLI plugin for vue-router._\n\nIf you click on `Repositories` and then on `IBM Carbon Tutorial` you'll notice a flicker as we hop from one page to another. We can fix this by using vue-router to manage our views.\n\nNext we need to update `src/App.vue` to render these views.\n\nIn the template section remove the `` and replace it with `` as follows\n\n#### src/App.vue\n\n```html\n\n \n\n```\n\nAfter that we need to do a couple quick fixes to the UI Shell to have it work with the vue-router.\n\n##### src/components/TutorialHeader/TutorialHeader.vue\n\nIn `src/components/TuturialHeader/TutorialHeader.vue` simply replace the `href` attributes used in the `cv-header-name` and `cv-header-menu-item` components with `to`. @carbon/vue will under the covers switch from use of an `a` tag to `router-link`.\n\n```html\nCarbon Tutorial\n```\n\nand\n\n```html\nRepositories\n```\n\nYou should now have a working header that routes to different pages without full page reload!\n\n## Submit pull request\n\nWe're going to submit a pull request to verify completion of this tutorial step and demonstrate a couple of related concepts.\n\n### Continuous integration (CI) check\n\nWe have a `ci-check` script defined in `package.json` that verifies file formatting for files that have been touched since the last Git commit with a tool called [Prettier](https://prettier.io). You'd typically also have that script run your test suite as part of your CI build. Go ahead and make sure everything looks good with:\n\n```bash\n$ yarn ci-check\n```\n\n_Note: If the_ `ci-check` _is giving an error, it's likely that some of your source files are not properly formatted. This could happen if your text editor isn't formatting with Prettier on save._\n\n\n\n\n### Git commit and push\n\nBefore we can create a pull request, stage and commit all of your changes:\n\n```bash\n$ git add --all && git commit -m \"feat(tutorial): complete step 1\"\n```\n\n\n\n\nThen, push to your repository:\n\n```bash\n$ git push origin vue-step-1\n```\n\n_Note: If your Git remote protocol is HTTPS instead of SSH, you may be prompted to authenticate with GitHub when you push changes. If your GitHub account has two-factor authentication enabled, we recommend that you follow these instructions to [create a personal access token for the command line](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line). That lets you use your token instead of password when performing Git operations over HTTPS._\n\n_Note: If you receive a_ `non-fast-forward` _error, it's likely that your forked repository is behind the original repository and needs updated. This can happen if the tutorial was updated after you began working on it. To fix, run_ `git pull upstream vue-step-1` _to merge the changes into your branch, then you can try pushing again. Or, you can [manually merge](https://help.github.com/en/articles/syncing-a-fork) in the upstream changes._\n\n### Pull request (PR)\n\nFinally, visit [carbon-tutorial-vue](https://github.com/carbon-design-system/carbon-tutorial-vue) to \"Compare & create pull request\". In doing so, make sure that you are comparing your repository's `vue-step-1` branch into `base: vue-step-1`. Take notice of the [Netlify](https://www.netlify.com) bot that deploys a preview of your PR every time that you push new commits. These previews can be shared and viewed by anybody to assist the PR review process.\n\n_Note: Expect your tutorial step PRs to be reviewed by the Carbon team but not merged. We'll close your PR so we can keep the repository's remote branches pristine and ready for the next person!_\n","fileAbsolutePath":"/zeit/3ed0734e/src/pages/tutorial/vue/step-1.mdx"}}}}