search

nimiq / vue-components

Vue component library for Nimiq ecosystem apps.
https://nimiq.github.io/vue-components/
Apache License 2.0
17 stars 4 forks source link

readme

Nimiq vue-components

This component library provides components written for the Vue frontend framework for use in Nimiq Ecosystem apps. Have a look at the demo page for an overview of included components.

Installation

yarn add github:nimiq/vue-components#build/master

This will install the complete component collection. To install only a subset for reduced bundle size, see section Advanced setup.

Some components require additional lazy-loaded assets which have to be copied over to your project. Specifically, these are translation files (if you want to support other languages than English), the Identicon svg asset and the QR scanner worker.

If your project has been created with the vue-cli / gets bundled via webpack, this can be conveniently done with the CopyWebpackPlugin:

const CopyWebpackPlugin = require('copy-webpack-plugin');

const plugins = [
    new CopyWebpackPlugin([
        // for translation files and additional, unnamed js chunks (currently only the qr scanner worker)
        {
            from: 'node_modules/@nimiq/vue-components/dist/NimiqVueComponents.umd.min.+(lang-*|[0-9]).js',
            to: './',
            flatten: true,
            transformPath(path) {
                // If you are bundling a non-minified build of the components (for later minification in your build
                // process; the default) it tries to also load the the non-minified language files, but we want
                // to load the minified files instead, so we rename them.
                return path.replace('.min', '');
            },
        },
        // for the identicons
        {
            from: 'node_modules/@nimiq/vue-components/dist/iqons.min.*.svg',
            to: './',
            flatten: true,
        },
    ]),
    ...
];

// webpack.config.js:
module.exports = {
  plugins,
  ...
};

// Or for projects created via vue-cli:
module.exports = {
    configureWebpack: {
        plugins,
    },
    ...
};

By default, these assets are resolved relatively to the importing script's location (the importing script's currentScript src) as base path. Alternatively, you can also specify a custom path:

import { setAssetPublicPath } from '@nimiq/vue-components';

setAssetPublicPath('/my-path/');

// Useful for projects setup via vue-cli to apply the app's public path to the vue-component assets
setAssetPublicPath(process.env.BASE_URL);

// You can also specify a separate folder for image assets
setAssetPublicPath('/js', '/img');

Updating

yarn upgrade @nimiq/vue-components

Usage

Import the components you want to use in your Vue component and define them as child components, for example:

import { LoadingSpinner } from '@nimiq/vue-components';

Vue.component('my-component', {
    components: { LoadingSpinner },
    template: `
        <div>
            Loading stuff...
            <LoadingSpinner />
        </div>
    `,
});

Advanced Setup

As this component library is built with webpack which does unfortunately currently not support outputting a tree-shakeable es6 module yet, we currently do not provide a package that supports tree-shaking and dead-code-elimination. To fix this, we will either wait for es6 module output support to be added to webpack, switch to building with rollup or release each component as separate package.

Until then, you have two options for including only a subset of the components in your code to reduce your bundle size:

  1. Import the unprocessed .vue single file components directly, for example import LoadingSpinner from '@nimiq/vue-components/src/components/LoadingSpinner.vue'. Note that for this to work, you need a bundler and build process that can handle .vue single file components and typescript. Also note that for some components additional setup might be required, for example for icon components imported from Icons.ts (see vue.config.js).

  2. Create a custom build of the vue-components that only includes the components you need. To do this, follow these steps:

    1. Fork this repository and git clone the fork to your computer.
    2. Comment-out all components and icons in main.ts and Icons.ts that you do not need.
    3. Build the source code via yarn && yarn build.
    4. Remove dist from .gitignore, then git add dist .gitignore to add the build output to your repository.
    5. Create a git commit and git push it to your fork respository.
    6. In your project, include the vue components from your fork, i.e. yarn add github:<your github organization or username>/vue-components

Development and testing

To install dependencies run:

yarn

To run the demo page locally with hot-reloading on changes to the code base:

yarn storybook

To check for linting errors:

yarn lint

To build the component library:

yarn build

Internationalization

First of all, a big thank you to all translators!

The Nimiq Vue-components are fully internationalized and ready for the community to add translations in different languages.

To help translate Vue-components, the procedure is as follows:

Additional information