sam-web-component-library v1.3.3
ECRS Vue Components
Overview
The goal of this library is to streamline the theme and interactions of the components used across ECRS applications. These components wrap the components provided by bootstrap-vue to abstract the component library away from ECRS applications, while at the same time taking advantage of these pre-existing elements. Ideally, if we ever choose to switch to a different 3rd party component library or write our own, all the work can be done in this project, and others will simply need to update to the latest version.
Setup
1 Setup NPM
This project is configured with an npmrc file. This file makes use of an environment variable called GITLAB_PERSONAL_ACCESS_TOKEN
. This token will authenticate you to interact with the GitLab npm registry for this project.
Follow these directions to generate a personal access token.
Now, make your token a Windows environment variable:
1. Copy your personal access token
2. Press Windows key and start typing "Edit the system environment variables"
3. Press enter when you see the above option appear
4. Click "Environment Variables"
5. Click "New..." under "User variables for user"
6. Input GITLAB_PERSONAL_ACCESS_TOKEN
in the box for "Variable name". The token name is important.
7. Paste your personal access token in the box for "Variable value"
8. Click "OK"
You should be left with something that looks like this:
2 Install Vue and Bootstrap via NPM
npm install vue bootstrap-vue bootstrap
3 Install the ECRS Vue Library
npm install
4 Import Bootstrap and ECRS Vue
Everything
// main.js
import Vue from 'vue';
import BootstrapVue from 'bootstrap-vue';
import ECRSVue from '@ecrs/vue';
// Load bootstrap styles and ECRS overrides
import 'bootstrap/dist/css/bootstrap.css';
import 'bootstrap-vue/dist/bootstrap-vue.css';
import '@ecrs/vue/dist/ecrs-vue.css';
Vue.use(BootstrapVue);
Vue.use(ECRSVue);
Optionally, styles can be loaded in a custom SCSS file. This will allow you to override variables with custom values:
// custom.scss
// Override variables here
// $primary: red;
// Import ecrs and bootstrap files last
@import '~@ecrs/vue/src/index.scss';
@import '~bootstrap/scss/bootstrap.scss';
@import '~bootstrap-vue/src/index.scss';
// main.js
import 'custom.scss';
Useful Tips
Icons
This library uses the vue-fontawesome component to allow using font awesome icons in Vue.
By default, ecrs-vue will only import the icons it needs to render its components. To easily hook into the icon loading, a list of icons can be passed in as options to the plugin:
import Vue from 'vue';
import BootstrapVue from 'bootstrap-vue';
import ECRSVue from '@ecrs/vue';
import { faPlusCircle } from '@fortawesome/free-solid-svg-icons';
Vue.use(BootstrapVue);
Vue.use(ECRSVue, {
icons: [
faPlusCircle
]
});
Note that the correct icon package will need to be installed for this to work
Project Development
Development in this project should be mandated by a mutual agreement that additional functionality should be added or bugs should be fixed.
Commands
Initialize project
npm install
Push package to the ECRS NPM Repository
npm publish
Compile and minify for production
npm run build
Scaffold the files needed for a new component
# Note that the -- is intentional npm run gen:component -- --name=<component-name>
Run lint tools to fix code formatting
npm run lint
Compile Storybook as static pages for deployment
npm run storybook:build
Run development mode with Storybook
npm run storybook:serve
Run unit tests
npm run test
Show npm dependency updates
npm run update
Tools
Vue
Each component is written with the Vue component library. As well, the build command will use the vue-cli-service to compile the library.
Storybook
Storybook is a development environment for previewing and interacting with components.
Jest
Jest enables unit testing at the component level. These test are run when using the test command.
ESLint & Stylelint
ESLint allows enforcing arbitrary formatting and error prevention rules in Javascript.
Stylelint provides the same functionality as ESLint, but to CSS/SCSS content.
Both of these are run when using the lint or test command.
npm-check and npm-audit-ci
These are CLI tools for managing package updates and ensures the testing phase fails if there are known vulnerabilities.
Setting Up Development with Another Project
While it is recommended that you use Storybook for isolated component development, it can be useful to edit a component in tandem with a separate project.
To temporarily setup this up:
- Run this command in this project
npm link
- Navigate to the other project that uses this one and run this command:
npm link @ecrs/vue
Now you can simply make your changes to your components and run the build command. The other project will pick up the changes without having to re-install them from NPM. If you need to use the npm hosted package, you can unlink the local version by running:
npm unlink @ecrs/vue
Creating a New Component
To scaffold the files needed for a new component, run the following command:
# Note that the -- is intentional
npm run gen:component -- --name=[component-name]
Where component-name is the name of the component. The name should follow these guidelines:
- These should not start with E (as you see all existing components do). This is added automatically
- The name should be proper case
Once this is done, 4 new files are generated:
- EComponent.vue - the actual component file
- EComponent.stories.js - the story entries for Storybook
- EComponent.spec.js - the Jes unit tests
- index.js - an entry point to installing the component as a plugin
Read the next sections to learn what to do with these files.
Component Development
Icons
This library used FontAwesome for its icons. To facilitate their usage, all icons should be added to icons.js
Unit Tests
npm run test:unit
Each component is required to have a unit test or building the project will fail. Tests are written with Jest testing library. Each component created comes with a sample test:
test('can be created', () => {
const wrapper = shallowMount(EInput, {});
expect(wrapper.isVueInstance()).toBe(true);
});
This test simply ensures that the component is created and is a valid Vue component.
Furthermore, the tests much reach a certain coverage threshold or they will fail.
Each of these test coverage categories must be meet or exceed 70% coverage:
- Statements - Has each statement in the program been executed?
- Branches - Has each conditional branch path been executed? (ei. for if statements, have both the if and else statements been executed)
- Functions - Has each function in the component been called?
- Lines - Has each executable line in the component been executed?
Stories
Each component is required to have a set of Storybook stories. A single story describes a component in a specific state. For example, the EButton component contains this story to demonstrate a button with text:
.add('with text', () => ({
components: { EButton },
template: '<e-button variant="primary" @click="action">Buttion Text</e-button>',
methods: { action: action('Clicked') }
}))
Stories should attempt to cover each state that a component can be in.
For complex components, knobs can be included to change the state of the UI rather than creating several stories. See the documentation on how to use the knobs addon.