@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. There is also a list of common commands.

As well as the library, there are some additional features in this repository designed to help us with development and production.

• Looking for a component? Checkout storybook.

• Looking to develop a new component? Have a peruse of components, storybook and dev.

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>

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 publish --access public: publish 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/components

This is where our component .vue files are located. At the time of writing, they aren't sorted into folders, but they will be. There are also the important files library.css and library.js 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 stylesheet in another project with import @uoe-ssp/style.css, or at least I hope you can.

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.

[TODO] Host a non-local version of storybook to help developers find components.

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

Get started with development right away by looking at some of stories or visit the storybook tutorial. You can also develop with the dev application bundled with this library.

src/dev

There is a development focussed application that comes with the library. You can load it up with npm run dev.

This command:

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

If you want a really basic way to develop your new component, this is it. Please don't overwrite the existing demo components though! You can also develop with storybook

When you are working on your component, you probably want to have changes hot loaded. So during development you can import your component (in src/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.

The existing development application installs components from dist/shared-components.js. Once your component is ready for production, you can also import it from shared-components.js, also 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:

• src/dev/index.js imports dist/style.css. dist/style.css 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/components/library.css without building it all the time, you might want to import it into src/dev/index.js directly.
• src/dev/index.js 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.
• src/dev/index.js also imports a small amount of #app and body styling from src/dev/app.css.
• src/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/components/library.js goes. Use npm run build to populate the dist folder with the component library files.

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!
• Publish to npm with npm publish --access public.
• 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/components/library.js.

There are two important files in the distribution folder.

• dist/shared-components.js is the component library that gets published.
• dist/style.css is the stylesheet, which contains all the individual component styling as well as any styling imported in src/components/library.js such as src/library.css and perhaps [TODO] an EdGel stylesheet.

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

For debugging 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'

scripts

If you are a developer who values their sanity don't read anything in scripts and don't run npm run edgel-combine. You're welcome!

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.

[TODO] We could choose to distribute a specific EdGel stylesheet for use within src/components/library.js which would mitigate the need for all of our projects to import EdGel.