Fundamental Vue Development Guide

If you want to contribute to Fundamental Vue this document is for you. This guide describes how to build, edit, test, document and debug Fundamental Vue locally. We will start from zero and describe each step of the way. Feel free to skip any steps you feel are not relevant to you.

Installing Yarn (required)

Fundamental Vue only works with Yarn. Trying to work on Fundamental Vue using anything else (e.g.: NPM) will fail. The reason is that Fundamental Vue consists of several projects (documentation app, the component framework, …) and to make things easy there are several scripts in our package.json-file which use Yarn to execute scripts defined in those sub-projects.

---

⚠️ WARNING: Fundamental Vue requires Yarn and does not work with NPM.

---

You should follow the official Yarn installation instructions in order to install Yarn.

Getting the Code

Clone the Fundamental Vue repository:

$ git clone git@github.com:SAP/fundamental-vue.git

Bootstrapping

Bootstrapping Fundamental Vue is required in the following situations:

• After cloning the repository.
• Every time the dependencies of any Fundamental Vue project changes.

Bootstrapping never hurts. So if in doubt, just bootstrap the project.

$ cd fundamental-vue
$ yarn bootstrap

Bootstrapping Fundamental Vue simply installs all the required dependencies of each sub-project.

Project Structure

Fundamental Vue consists of several sub-projects. After bootstrapping Fundamental Vue the root directory should look something like this:

.
├── README.md
├── DEV.md (this guide)
├── Fundamental-Vue.code-workspace
├── package.json
├── node_modules/
├── …
├── ui/
│   ├── node_modules/
│   ├── src/
│   ├── …
│   └── package.json
├── docs/
│   ├── node_modules/
│   ├── src/
│   ├── …
│   └── package.json
├── server/
│   ├── node_modules/
│   ├── index.js
│   └── package.json
└── …

You will notice the three sub-projects:

• ui: Fundamental Vue component library
• docs: Fundamental Vue documentation app
• server: Development server

You can cd into every project and use it independently. Alternatively you can stay in the root directory and manage everything from there.

Editing the Source Code

You can edit the source code using (almost) any editor. However, we highly recommend using Visual Studio Code. If you are using Visual Studio Code you can simply use it top open the workspace file Fundamental-Vue.code-workspace.

Serving the Documentation & Components

Let's assume you made a change to the source code. The next thing you probably want is to see your changes. The best way to see your change is to serve the documentation:

$ yarn serve

This simply command is doing a lot of things in the background. If you want the know the details you may look at the corresponding script in the package.json file. On a high level yarn serve is doing three things:

1. It continously builds the ui-project (in development mode)
2. It continously serves the documentation-app.
3. It starts the development server.

As a side effect, the linter will also run in the background and log any issue to the console.

While yarn serve is executing you can browse the documentation by going to http://localhost:8080.

Executing tests

There are two Yarn-scripts related to testing.

Execute all tests:

$ yarn test

Execute all tests and watch for changes:

$ yarn test:watch

Debugging Tests:

It is possible to debug tests. The following instructions work by using Visual Studio Code. There may be other ways to debug tests but up to this point there was no need to debug tests in another way. If you are not using Visual Studio Code and have the need to debug tests please create an issue.

1. Install the official Jest extension for Visual Studio Code.
2. You may have to reload Visual Studio Code if you are using a version of Visual Studio Code released before February 2019.
3. Add the following setting to your settings.json file:

{
  "jest.debugCodeLens.showWhenTestStateIn": [
    "fail", "unknown", "pass", "skip"
  ]
}

This ensures that Jest's code lenses are always visible in tests.

4. Make sure that Auto Attach is turned on.
5. Open a terminal and cd into the ui-directory.
6. Set a breakpoing in a test of interest (using Visual Studio Code) and then execute the following command:

$ node --inspect-brk ./node_modules/.bin/vue-cli-service test:unit --runInBand

Production Build

If you want to create a production build of Fundamental Vue and the documentation simply execute:

$ yarn build

After a successful build you should see the artefacts in the dist-folder.

Creating an NPM Package

Once you have a production build in your dist-folder simply execute

$ npm pack

This will create a tarball that can be used by Yarn or NPM.