1. Installing Carbon
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.
- Fork, clone and branch
- Build and start
- Install Carbon
- Other dependencies
- Add UI Shell
- Create pages
- Add routing
- Submit pull request
Preview
A preview of what you will build:
Fork, clone and branch
This tutorial has an accompanying GitHub repository called carbon-tutorial-vue that we’ll use as a starting point for each step.
Fork
To begin, fork carbon-tutorial-vue using your GitHub account.
Clone
Go 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.
git clone [your fork SSH/HTTPS]cd carbon-tutorial-vue
Add upstream remote
Add a remote called upstream
so we can eventually submit a pull request once
you have completed this tutorial step.
Or, if you prefer to use HTTPS instead of SSH with your remotes:
git remote add upstream https://github.com/carbon-design-system/carbon-tutorial-vue.git
Verify that your forked repository remotes are correct:
git remote -v
Your terminal should output something like this:
origin [your forked repo] (fetch)origin [your forked repo] (push)
Branch
Now that we have our repository set up, let’s check out the branch for this tutorial step’s starting point. Run the two commands:
git fetch upstreamgit checkout -b vue-step-1 upstream/vue-step-1
Build and start
We 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:
yarn
After the dependencies are installed, you can start the app with:
yarn serve
Your 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.
OK. So we made a small change to the Vue CLI generated app replacing the HelloWorld component and replaced it with our own message and swapped out the favicon.
Install Carbon
Even though we installed existing dependencies, we’ve yet to install the Carbon packages.
carbon-components
- component styles@carbon/vue
- Vue components@carbon/icons-vue
- Vue icons
Stop your development server with CTRL-C
and install Carbon dependencies with:
yarn add carbon-components @carbon/vue @carbon/icons-vue
Other dependencies
If 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:
vue-router
: Used to make routing in Vue apps simpler@vue/cli-plugin-babel
: To ensure we produce well supported code.@vue/cli-plugin-eslint
: To allow us to catch potential errors.@vue/cli-plugin-unit-jest
: To allow us to unit test our code.sass-loader
: To allow us to use the sass css precompiler.
NOTE: We could have installed these separately but using the CLI to set this up for us ensures a good base config for these dependencies.
To avoid having to add the ~
prefix when importing SCSS files from
node_modules
, create a .env
file at the project root that contains:
.envSASS_PATH="node_modules"
For the Windows operating system, use:
.envSASS_PATH=./node_modules
Then, start the app again. If your app’s currently running, you’ll need to restart it for the new environment variable to be used.
yarn serve
The app looks as it did before. Next, let’s add Carbon styling.
Import carbon-component styles
In 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.
src/App.vue<style lang="scss">@import "./styles/carbon";</style>
In styles/_carbon.scss
, import the Carbon styles by adding the following at
the top of the file:
src/styles/_carbon.scss@import 'carbon-components/scss/globals/scss/styles';
This 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.)
Because 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 separate file if needed.
Next we’ll create a Carbon Button
to test that our dependencies are working
properly.
After the other imports in main.js and before the Vue instance is created add the following.
src/main.jsimport CarbonComponentsVue from "@carbon/vue";Vue.use(CarbonComponentsVue);
This 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.
e.g. Instead of modifying src/main.js we could have added the following to src/App.vue:
src/App.vue<script>import { CvButton } from '@carbon/vue';export default {components: {CvButton,}};</script>
See the Carbon Vue Components documentation for other ways to load components from @carbon/vue components.
In this tutorial we will stick to importing all of the components at once so we can focus on our use of @carbon/vue.
Now open the App.vue
component and replace:
src/App.vueHello Carbon! Well, not quite yet. This is the starting point for the Carbon tutorial.
with:
src/App.vue<CvButton>Button</CvButton>
or
<cv-button>Button</cv-button>
Congratulations, you’ve imported your first component! You should see a Carbon styled button on the page.
NOTE: In this tutorial you can use either tag format. The Vue 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.
Add UI Shell
Next 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
:
src/components/TutorialHeader├──index.js└──TutorialHeader.vue
Import and export the header
In src/components/TutorialHeader/index.js
, import and export our
TutorialHeader
component like so:
src/components/TutorialHeader/index.jsimport TutorialHeader from './TutorialHeader';export default TutorialHeader;
Lazyness - VSCode users only
If 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.
javascript.json"index-file": {"prefix": "index","body": ["import ${TM_DIRECTORY/.*[\\/]//gm} from './${TM_DIRECTORY/.*[\\/]//gm}';","export { ","\t${TM_DIRECTORY/.*[\\/]//gm},","};","export default ${TM_DIRECTORY/.*[\\/]//gm}",""
You 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.
vue.json"Vue_Component": {"prefix": "template","body": ["<template>","\t$0","</template>","","<script>","export default {",
OK, back to using Carbon components. Let’s make use of our Carbon UI Shell
components in TutorialHeader.vue
. Set up the file like so:
src/components/TutorialHeader/TutorialHeader.vue<template><cv-header aria-label="Carbon tutorial"><cv-skip-to-content href="#main-content">Skip to content</cv-skip-to-content><cv-header-name href="/" prefix="IBM">Carbon Tutorial</cv-header-name><cv-header-nav>
Import icons
Now 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.
src/components/TutorialHeader/TutorialHeader.vue<script>import { Notification20, UserAvatar20, AppSwitcher20 } from '@carbon/icons-vue';export default {name: "TutorialHeader",components: { Notification20, UserAvatar20, AppSwitcher20 }};</script>
Then 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:
src/components/TutorialHeader/TutorialHeader.vue<template slot="header-global" />
With:
src/components/TutorialHeader/TutorialHeader.vue<template slot="header-global"><cv-header-global-action aria-label="Notifications"><notification-20 /></cv-header-global-action><cv-header-global-action aria-label="User avatar"><user-avatar-20 /></cv-header-global-action><cv-header-global-action aria-label="App switcher"><app-switcher-20 />
Render the header
Next we’ll render our UI Shell by importing our Tuto