@unraid/shared-components NPM

shared-components

Usage Instructions

Add to your Unraid Vue.js project. Note that you must have access to the Unraid NPM Org and have an Access Token added to your ENV that has the correct permissions.

npm i @unraid/shared-components

Animated Unraid Logo Loader

<template>
    <div class="tw-flex tw-flex-wrap tw--mx-3">
        <div v-if="loading" class="tw-w-full tw-flex tw-justify-center tw-p-16">
            <unraid-loading class="tw-max-w-140px tw-px-3" />
        </div>
        <some-fancy-component v-else />
    </div>
</template>

<script>
import { UnraidLoading } from '@unraid/shared-components';
…
export default {
    …
    components: {
      UnraidLoading,
      …
    },
    …
};
</script>

SVG Icon Component

Uses svg-sprite to generate an SVG Sprite based on individual files with ./assets/svg/**/.

Then in Vue vue-svg-sprite is used within our .vue templates to display the SVGs from the generated SVG Sprite.

Pre-usage Setup

If you don't already have svg-sprite installed globally run yarn global add svg-sprite.

Because npm packages aren't really intended to have assets like images or font files we need to add a postinstall script to the parent project's package.json that will be using this SVG component of shared-components. This ensures the parent project can generate the SVG sprite and save it to the project's directory.

Step 1

"postinstall": "svg-sprite --config node_modules/@unraid/shared-components/svg-sprite.config.json 'node_modules/@unraid/shared-components/assets/svg/./**/*.svg'"

Step 2

You'll also want to update your .gitignore to include the directory that's created on postinstall

references that helped me figure this out:

Using the `UnraidSvgIcon` component in your project

Symbol names are automatically generated based on the individual SVG file's location. For example, if your SVG is located at assets/svg/ui/example.svg then the symbol prop value will be ui--example.

<template>
  <div>
    …
      <p class="tw-relative tw-mt-3 tw-pl-8">
        <!-- 
          - The symbol prop is required. Refer to SVGs in assets dir for options.
          - Uses classes to size and style your SVG
        -->
        <unraid-svg-icon 
          symbol="ui--example"
          class="tw-absolute tw-top-0 tw-left-0 tw-w-4 tw-h-4 tw-mr-2" />
        <a :href="exampleUrl" target="_blank">{{ exampleDetails }}</a>
      </p>
    …
  </div>
</template>
<script>
import { UnraidSvgIcon } from '@unraid/shared-components';
…
export default {
    …
    components: {
        …
        UnraidSvgIcon
    },
    …
}
</script>

Adding a new icon to the SVG Sprite (WIP)

Export your SVG with no fill. Sometimes in your editor this means setting the fill to #000000.
Remove any width or height attributes from the SVG Code (this may not be necessary, will determine soon)
Add your raw exported SVG file to assets/svg/<relevant_dir>/
Commit the new SVG to the repo
Push to origin
Now in your project you should be able to run yarn upgrade @unraid/shared-components to get the new version of the shared-components repo / "package".
- Because we added the postinstall script to our project's package.json after running yarn the new version of the SVG Sprite was generated.
Now refer to the usage instructions above, referencing your new SVG via the symbol prop for the component.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

yarn install
yarn serve
yarn build
yarn test:unit
yarn test:e2e
yarn lint

Adding a Component

Checkout a new topic branch
Create your new .vue component file in src/components
Import your new component to src/app.vue so you can see it for development purposes
Add your new component to be exported src/components/index.js. Following the same naming convention that's already in place.