@uoe-ssp/shared-components

Introduction

This is the readme for the University of Edinburgh Student Systems Partnerships Vue3 component library. In npm speak, that is @uoe-ssp/shared-components. We keep and develop components here, to make it easy to share components between projects.

Find out how to use this library by getting started. You can also learn how to contribute.

As well as the library, there are some additional features in this repository designed to help us with development and production. You might find the list of common commands helpful.

• Looking for a component? Read storybook.

• Looking to develop a new component? Read how to contribute.

Getting started

At its core, this is a library first and foremost. Install the library in your Vue project:

npm install @uoe-ssp/shared-components

Then, use the components you want in your projects .vue files like this:

import { SharedComponentName, AnotherSharedComponent } from '@uoe-ssp/shared-components'

...

<template>
    <SharedComponentName :prop="firstProp" :otherProp="anotherProp">Slot Content</SharedComponentName>
</template>

Contributing

You don't just want to use the library, you want to contribute? Even better.

Install this project and it's dependencies with: npm install.

Then read the components, storybook and dev sections to understand where to add components and how you can go about developing them.

Common commands

npm install: install this project on your machine, usually for development purposes.

npm run storybook: load up storybook for development or to find a component, read storybook.

npm run dev: run a local application for development, read dev.

npm run build: create a distribution folder ready for publishing or using locally, read dist.

npm run pub: builds then publishes the library to npm, read dist.

You can find and define other commands in the package.json.

Project structure

• components
• storybook
• dev
• dist
• scripts

src

The files library.css and library.js are loose in here.

• library.js defines the exports for the project -- it is very important! Go look at it.
• library.css is a place for defining global styling for uoe-ssp/shared-components. It is exported along with the components individual styles. Styling isn't all worked out yet... but you can import the combined library/component stylesheet in another project with import @uoe-ssp/shared-components/shared-components.css, or at least I hope you can.

src/components

This is where our component .vue files are located, and this is where you would add new components. Develop or migrate components using storybook and test the exports in an external application, like the vue3-template application. The components make up the core of the library that is built to dist.

They have been sorted in an atomic design fashion.

Don't forget to export your component in src/library.js once you've made it

src/stories and .storybook

Storybook is a way of doing lots of things -- but here we are primarily using it to find, develop (and maybe in future test) components. It has a really nice user interface that you can see by running npm run storybook.

We host a version of storybook on our development server that can be used to help people find components without installing this vue-shared-components project. There is also a bamboo plan for this storybook deployment.

When you are developing a new component, or migrating one from somewhere else, writing a story for it is really helpful. Regardless of how you develop your component, please write a story for it when it is finished so that other people can find it.

Storybook is configured in .storybook and stories are written in src/stories.

The simplest example story to get you started is in @/stories/SimpleExample.stories.js. Then, when you want or need to add props or other information take a look at @/stories/atoms/GenericLink.vue and for more advanced behaviour investigate @/stories/atoms/UiButton.vue.

I'd also suggest going through the storybook tutorial.

Storybook doesn't play nicely with router components. So we have @/stories/ssp-vueRouter-addon.js to help us decorate stories that need a router. You can find documentation for it in the storybook-vue3-router github repo.

For stores, we have taken the approach of injecting the pinia instance and any other store configuration in .storybook/preview.js. This hopefully reflects the design we will use in other applications (injecting in some src/main.js file in-place of preview.js).

Finally if storybook isn't working for you, you can also develop with the dev application bundled with this library.

dev

There is a development focussed application that comes with the library. It is also a working example of how the library works

The preferred development workflow is to develop with storybook and test the component in another application. The vue3-template application is perfect for this purpose.

Still, if you want a really basic and local way to develop your new component, or test some change to the dist/ files this is it. Please don't overwrite the existing demo components though! After you have built the library with npm run build you can load the development application with npm run dev.

This command:

• loads dev/index.html
• which loads dev/main.js
• which imports dev/App.vue.

When you are working on your component, you probably want to have changes hot loaded. So during development you can import your component (in dev/App.vue) like:

import { MyComponent } from '@/components/MyComponent.vue'

and then changes made to my component should automatically be reflected in the app you have started with npm run dev.

Once your component is ready for production, you can also import it from shared-components.js (after building the library). Read the section on distribution.

Remember you need to run npm run build to have changes to src/components reflected in dist/*.

A note on the styling of the development application -- this app is styled in a bunch of different ways, it can get confusing:

• dev/main.js imports dev/app.css. app.css imports dist/shared-components.css which is a combination of all the individual component styles, defined under src/components/.../MyComponents.vue and also src/libary.css. However, it only includes the css files that have been built as part of npm run build. So if you want to develop src/library.css without building it all the time, you might want to import it into dev/main.js directly.
• app.css also imports an EdGel styling, at the time of writing that is @uoe/edgel/css/edgel-blue-bright.css. This includes a bunch of useful classes, and generally we are trying to use EdGel styles (and maybe components) where we can. Have a read of the EdGel section of the readme for more on that.
• dev/App.vue contains even more component level styling.
• Finally, if you are installing your components from @/components/MyComponent.vue then any styling you have defined in the components will be included and the dev application will reload when you make changes.

dist

This is where the production ready library of components, defined in src/library.js goes. Use npm run build to populate the dist folder with the component library files. Don't forget to export your component in src/library.js once you've made it

For development purposes you can locally import the component library into another project like:

import { SharedComponentName, AnotherSharedComponent } from 'C:/Users/shende2/Code/projects/vue3-shared-components/vue-shared-components/dist/shared-components.js'

This is a really good way of testing that your component exports correctly and works in another application.

Distribution will be handled by publishing to npm.

• Update the package.json version before publishing and remember that the version you will publish is published forever!
• Build and publish in one command: npm run pub.
• Import it into another project after publishing with: npm install @uoe-ssp/shared-components.

The distribution config is defined in vite.config.js and in the package.json. The exports/components included in the library are defined in src/library.js.

There are two important files in the distribution folder.

• dist/shared-components.js is the component library that gets published.
• dist/shared-components.css is the stylesheet, which contains all the individual component styling as well as any styling imported in src/library.js (and therefore src/library.css).

You might want to import the library stylesheet in your project: import @uoe-ssp/shared-components/shared-components.css.

EdGel

Not to be confused with the University gel pen start-up, EdGel/EdGel on Gitlab is the University of Edinburgh's Bootstrap 5 theme. It includes a bunch of .css files, as well as more experimental custom web-components created using Lit.

[TODO] We might be able to import and use or re-export those components in this library.

uoe-ssp/shared-components should be compatible with EdGel 5. You can try out the different brand themes in storybook.