Repository: wuruoyun/vue-component-lib-starter
Branch: master
Commit: c80d0e2df5c1
Files: 27
Total size: 18.9 KB

Directory structure:
gitextract_4x8huyf1/

├── .gitignore
├── .nvmrc
├── README.md
├── docs/
│   ├── .vitepress/
│   │   ├── components/
│   │   │   └── DemoContainer.vue
│   │   ├── config.js
│   │   └── theme/
│   │       ├── custom.css
│   │       └── index.js
│   ├── components/
│   │   ├── component-a.md
│   │   ├── component-b.md
│   │   ├── demo/
│   │   │   ├── ComponentA/
│   │   │   │   └── Basic.vue
│   │   │   └── ComponentB/
│   │   │       └── Basic.vue
│   │   └── index.md
│   ├── guide/
│   │   └── index.md
│   └── index.md
├── package.json
├── src/
│   ├── assets/
│   │   └── main.scss
│   ├── components/
│   │   ├── ComponentA.vue
│   │   ├── ComponentB.vue
│   │   └── index.ts
│   ├── constants/
│   │   ├── MyConstants.ts
│   │   └── index.ts
│   ├── env.d.ts
│   ├── index.ts
│   └── utils/
│       ├── MyUtil.ts
│       └── index.ts
├── tsconfig.json
└── vite.config.ts

================================================
FILE CONTENTS
================================================

================================================
FILE: .gitignore
================================================
node_modules
.DS_Store
dist
dist-ssr
*.local
docs/.vuepress/.cache
docs/.vuepress/.temp
types


================================================
FILE: .nvmrc
================================================
lts/*


================================================
FILE: README.md
================================================
[![Netlify Status](https://api.netlify.com/api/v1/badges/b1b84831-789e-4629-a9e3-55a36e136653/deploy-status)](https://app.netlify.com/sites/sharp-babbage-154f0a/deploys)

# Vue Component Library Starter

> Create your own [Vue 3](https://v3.vuejs.org/) component library with TypeScript, [Vite](https://vitejs.dev) and [VitePress](https://vitepress.vuejs.org/).

Sooner or later, you will find that creating a component library is much better than having all components inside your app project. A component library force to you remove app specific logic from your components, making it easier to test and reuse them in other apps.

Once the components are in a library, documentation becomes critical. This starter project includes a documentation app powered by VitePress. It not only documents the usage of the component, but also provides a testing bed during the development of components. See the generated documentation app [here](https://sharp-babbage-154f0a.netlify.com/).

## Setup

> When running `docs:dev` for the first time, you may encounter error like `vitepress data not properly injected in app` in your browser. Restart the server and reload the browser. Please refer to [issue #30](https://github.com/wuruoyun/vue-component-lib-starter/issues/30) for more details.

```bash
# install dependencies
npm install

# start the doc app with hot reload, great for testing components
npm run docs:dev

# build the library, available under dist
npm run build

# build the doc app, available under docs/.vitepress/dist
npm run docs:build

# preview the doc app locally from docs/.vitepress/dist
npm run docs:serve
```

You may use [Netlify](https://www.netlify.com/) to auto build and deploy the doc app like this project does.

## Develop and test locally

The best way to develop and test your component is by creating demos in `docs/components/demo` folder, as shown by the example components.

If you want to test the library in your Vue3 app locally:

- In the root folder of this library, run `npm link`. This will create a symbolic link to the library.
- In the root folder of your client app, run `npm link my-lib`. This will add the symbolic link to the `node_modules` folder in your client app.
- You can now import `my-lib` in your client app.

There is no need to add `my-lib` to your client app's dependency in this case.

If you made changes to the library, you will need to rebuild the library. Your Vue3 app shall hot reload when the building of library is completed.

## How it works

### Components

The library is a [Vue plugin](https://v3.vuejs.org/guide/plugins.html). The `install` function in [index.ts](src/index.ts) registers all components under [components](src/components) to Vue globably.

The components are also exported by [index.ts](src/index.ts) so that the client app can import them individually and register them locally, instead of using the library as a plugin. This may be a better option if the client app only use a small set of components in your library.

As there are already many UI component libraries for Vue 3, you may just want to build on top of one of them and create components for your specific needs. The Component B in this starter shows the example of using [PrimeVue](https://www.primefaces.org/primevue/) as the fundation library. However, this means the client app shall also use the same fundation component library as your library does.

The doc app itself is a client app of the libary, therefore PrimeVue is imported in [docs/.vitepress/theme/index.js](docs/.vitepress/theme/index.js). The configuration in [docs/.vitepress/config.js](docs/.vitepress/config.js) below forces VitePress to resolve these modules with no duplication, avoiding error at runtime, as PrimeVue also has Vue in its dependency.

```js
module.exports = {
  vite: {
    resolve: {
      dedupe: ['vue', /primevue\/.+/],
    },
  },
}
```

> In [vite.config.ts](vite.config.ts), format 'umd' is not present in `build.lib.formats` option. This is because the PrimeVue components used by this library are externalized, and therefore requiring corresponding options in `rollupOptions.output.globals`. To avoid adding global varaibles for PrimeVue components, 'umd' is removed for simplicity.

### Utilities and constants

The library includes example utilities and constants. They are also exported in [index.ts](src/index.ts). The client app may use them as below:

```js
<script lang="ts">
import { MyConstants, MyUtil } from 'my-lib'

export default {
  data () {
    return {
      magicNum: MyConstants.MAGIC_NUM
    }
  },
  methods: {
    add (a:number, b:number) {
      return MyUtil.add(a, b)
    }
  }
}
</script>
```

### Styling

Individual components may have styles defined in its `.vue` file. They will be processed, combined and minified into `dist/style.css`, which is included in the `exports` list in [package.json](package.json).

If you have library level styles shared by all components in the library, you may add them to [src/assets/main.scss](src/assets/main.scss). This file is imported in [index.ts](src/index.ts), therefore the processed styles are also included into `dist/style.css`. To avoid conflicting with other global styles, consider pre-fixing the class names or wrapping them into a namespace class.

If you have your own special set of SVG icons, you may create a font file (`.woff` format) using tools like [Icomoon](https://icomoon.io/) or [Fontello](https://fontello.com/). This starter includes an example font file [src/assets/fonts/myfont.woff](src/assets/fonts/myfont.woff) and references it in [src/assets/main.scss](src/assets/main.scss), with utility icon CSS classes. An icon from the font file is used in Component A. Vite will include the font file into the build, see [https://vitejs.dev/guide/assets.html](https://vitejs.dev/guide/assets.html).

The client app shall import `style.css`, usually in the entry file:

```js
import 'my-lib/dist/style.css'
```

### Third-party dependencies

Third-party libraries used by you library may bloat up the size of your library, if you simply add them to the `dependencies` in [package.json](package.json).

The following are some strategies to reduce the size of your library:

#### Externalization

If you expect the client app of your library may also need the same dependency, you may externalize the dependency. For example, to exclude PrimeVue from your library build artifact, in [vite.config.ts](vite.config.ts), you may have

```js
module.exports = defineConfig({
    rollupOptions: {
      external: ['vue', /primevue\/.+/]
    }
  }
})
```

The dependency to be externalized may be declared as peer dependency in your library.

#### Cherry picking

If you don't expect the client app of your library also needing the same dependency, you may embed cherry-picked functions. For example, to embed the `fill` function of popular library [lodash](https://lodash.com), import the `fill` function like the following:

```js
import fill from 'lodash/fill'
```

Even with tree-shaking, the codes being brought into your library may still be large, as the function may have its own dependencies.

Note that `import { fill } from 'lodash'` or `import _ from 'lodash'` will not work and will embed the whole `lodash` library.

Finally, if your client app also use `lodash` and you don't want `lodash` to be in both the client app and your libraries, even after cherry-picking, you may consider cherry-picking in component library and re-export them as utils for client to consume, so that the client does not need to depend on `lodash`, therefore avoiding duplication.

### Type generation

In [tsconfig.json](tsconfig.json), the following options instructs `tsc` to emit declaration (`.d.ts` files) only, as `vite build` handles the `.js` file generation. The generated `.d.ts` files are sent to `dist/types` folder.

```json
"compilerOptions": {
  "declaration": true,
  "emitDeclarationOnly": true,
  "declarationDir": "./dist/types"
}
```

In [package.json](package.json), the line below locates the generated types for library client.

```json
"types": "./dist/types/index.d.ts",
```

> In [vite.config.ts](vite.config.ts), `build.emptyOutDir` is set to `false` and `rimraf` is used instead to remove the `dist` folder before the build. This is to avoid the `dist/types` folder generated by `tsc` being deleted when running `vite build`.

### Configuration

#### TypeScript

In [tsconfig.json](tsconfig.js), set the following as recommended by Vite (since esbuild is used). However, enableing this option leads to https://github.com/vitejs/vite/issues/5814. The workaround is to also enable `compilerOptions.skipLibCheck`.

```json
"compilerOptions": {
  "isolatedModules": true
}
```

In [tsconfig.json](tsconfig.js), set the following to address [Issue #32](https://github.com/wuruoyun/vue-component-lib-starter/issues/32). The solution is from https://github.com/johnsoncodehk/volar/discussions/592.

```json
"compilerOptions": {
  "types": [
    "vite/client"
  ]
}
```


================================================
FILE: docs/.vitepress/components/DemoContainer.vue
================================================
<template>
  <div class="demo-container">
    <slot></slot>
  </div>
</template>

================================================
FILE: docs/.vitepress/config.js
================================================
const path = require('path')

module.exports = {
  title: 'My Lib',
  description: 'Just playing around.',
  themeConfig: {
    repo: 'https://github.com/wuruoyun/vue-component-lib-starter',
    sidebar: [
      {
        text: 'Introduction',
        children: [
          { text: 'What is My Lib?', link: '/' },
          { text: 'Getting Started', link: '/guide/' },
        ],
      }, {
        text: 'Components',
        children: [
          { text: 'Component A', link: '/components/component-a' },
          { text: 'Component B', link: '/components/component-b' },
        ],
      }
    ],
  },
  vite: {
    resolve: {
      alias: {
        'my-lib': path.resolve(__dirname, '../../src'),
      },
      dedupe: ['vue', /primevue\/.+/], // avoid error when using dependencies that also use Vue
    }
  }
}


================================================
FILE: docs/.vitepress/theme/custom.css
================================================
.demo-container {
  border: 1px solid lightgrey;
  border-radius: 5px;
  padding: 10px 20px;
}

================================================
FILE: docs/.vitepress/theme/index.js
================================================
import DefaultTheme from 'vitepress/theme'
import PrimeVue from 'primevue/config'
import DemoContainer from '../components/DemoContainer.vue'
import MyLib from 'my-lib'

import 'primevue/resources/themes/saga-blue/theme.css'       //theme
import 'primevue/resources/primevue.min.css'                 //core css
import 'primeicons/primeicons.css'
import 'primeflex/primeflex.css'

import './custom.css'

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    app.use(PrimeVue)
    app.use(MyLib)
    app.component('DemoContainer', DemoContainer)
  }
}


================================================
FILE: docs/components/component-a.md
================================================
<script setup>
import Basic from './demo/ComponentA/Basic.vue'
</script>

# Component A

This is a simple Hello Word component with a prop and use icon <span class="icon-heart" style="color:tomato"></span> from a font file.

## Example Usage

You may show demo below with the code snippet.

<DemoContainer>
  <Basic/>
</DemoContainer>

<<< @/components/demo/ComponentA/Basic.vue

## Reference

You may show props, slots, events, methods, etc. using Markdown.

### Properties

| Name | Type   | Default | Description    |
| ---- | ------ | ------- | -------------- |
| msg  | string | null    | Messge to show |

### Events

| Name | Parameters | Description |
| ---- | ---------- | ----------- |
|      |            |             |

### Slots

| Name | Parameters | Description |
| ---- | ---------- | ----------- |
|      |            |             |


================================================
FILE: docs/components/component-b.md
================================================
<script setup>
import Basic from './demo/ComponentB/Basic.vue'
</script>
# Component B

This component depends on third-party component library for Vue 3:

* Component (button) from [PrimeVue](https://www.primefaces.org/primevue/)
* CSS from [PrimeIcons](https://www.primefaces.org/showcase/icons.xhtml) and [PrimeFlex](https://www.primefaces.org/primeflex/)

## Example Usage

Click the buttons to change the count.

<DemoContainer>
  <Basic/>
</DemoContainer>

<<< @/components/demo/ComponentB/Basic.vue

## Reference
You may show props, slots, events, methods, etc. using Markdown.

### Properties

| Name        | Type     | Default  | Description     |
| ----------- | -------- | -------- | --------------- |
|             |          |          |                 |

### Events

| Name        | Parameters   | Description     |
| ----------- | ----------   | --------------- |
|             |              |                 |

### Slots

| Name        | Parameters   | Description     |
| ----------- | ----------   | --------------- |
|             |              |                 |


================================================
FILE: docs/components/demo/ComponentA/Basic.vue
================================================
<template>
  <ComponentA msg="World"/>
</template>

================================================
FILE: docs/components/demo/ComponentB/Basic.vue
================================================
<template>
  <ComponentB/>
</template>


================================================
FILE: docs/components/index.md
================================================
# Components

You may add a summary of the components here.

================================================
FILE: docs/guide/index.md
================================================
# Getting Started

You may add the usage of the library here.

> If you remove Component B and the [PrimeFaces](https://www.primefaces.org/) (PrimeVue, PrimeIcons and PrimeFlex) dependencies from your library, the setup related to PrimeFaces won't be needed from the guide below.

## Setup

This setup assumes your client app is created with Vite and vue-ts template, and you use 'npm link' to link to `my-lib` locally.

In your `package.json`, you shall have the dependencies compatible with the following:

```json
"dependencies": {
  "primeflex": "^3.1.2",
  "primeicons": "^5.0.0",
  "primevue": "^3.11.1",
  "vue": "^3.2.25"
}
```

In your `vite.config.ts`, you shall configure to dedupe `vue`:

```ts
export default defineConfig({
  resolve: {
    dedupe: ['vue'],
  },
});
```

In your `main.ts`, you shall import the libraries and CSS:

```ts
import 'primevue/resources/themes/saga-blue/theme.css';
import 'primevue/resources/primevue.min.css';
import 'primeicons/primeicons.css';
import 'primeflex/primeflex.css';

import 'my-lib/dist/style.css';
```

Import components from this library in your own component:

```html
<script setup lang="ts">
  import { ComponentA, ComponentB } from 'my-lib';
</script>
```


================================================
FILE: docs/index.md
================================================
# What is My Lib?

This library is a starter to create your own Vue 3 component library in TypeScript.

There are two example components included for you to get started with creating your own components:

- [ComponentA](/components/component-a) is a simple Hello World component with icon from bundled font file.
- [ComponentB](/components/component-b) is a counter component using button from [PrimeVue](https://www.primefaces.org/primevue/), icons from [PrimeIcons](https://www.primefaces.org/showcase/icons.xhtml) and styling from [PrimeFlex](https://www.primefaces.org/primeflex/).


================================================
FILE: package.json
================================================
{
  "name": "my-lib",
  "version": "0.0.0",
  "scripts": {
    "build": "rimraf dist && vue-tsc && vite build",
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:serve": "vitepress serve docs"
  },
  "peerDependencies": {
    "primeflex": "^3.3.1",
    "primeicons": "^6.0.1",
    "primevue": "^3.29.2",
    "vue": "^3.3.4"
  },
  "devDependencies": {
    "@types/node": "^20.3.3",
    "@vitejs/plugin-vue": "^4.2.3",
    "rimraf": "^5.0.1",
    "sass": "^1.63.6",
    "typescript": "^5.1.6",
    "vite": "^4.3.9",
    "vitepress": "^0.22.4",
    "vue-tsc": "^1.8.3"
  },
  "files": [
    "src",
    "dist"
  ],
  "module": "./dist/my-lib.es.js",
  "exports": {
    ".": {
      "types": "./dist/types/index.d.ts",
      "import": "./dist/my-lib.es.js"
    },
    "./dist/style.css": "./dist/style.css"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/wuruoyun/vue-component-lib-starter.git"
  }
}


================================================
FILE: src/assets/main.scss
================================================
@font-face {
  font-family: 'myfont';
  src: url('fonts/myfont.woff');
}

[class^='icon-'],
[class*=' icon-'] {
  font-family: 'myfont' !important;
}

.icon-heart:before {
  content: '\e9da';
}

.global-example {
  color: red;
}


================================================
FILE: src/components/ComponentA.vue
================================================
<script setup lang="ts">
interface Props {
  msg: string
}

const props = defineProps<Props>()
</script>

<template>
  <div>
    Hello {{ msg }}! <span class="icon-heart" style="color:tomato"></span>
  </div>
</template>


================================================
FILE: src/components/ComponentB.vue
================================================
<script setup lang="ts">
import { ref } from 'vue'
import Button from 'primevue/button'
const count = ref(0)
</script>

<template>
  <div class="flex align-content-center flex-wrap counter">
    <label class="flex align-items-center justify-content-center">Counter:</label>
    <Button icon="pi pi-plus" class="p-button-sm flex align-items-center justify-content-center" @click="count++"></Button>
    <span class="flex align-items-center justify-content-center count">{{ count }}</span>
    <Button icon="pi pi-minus" class="p-button-sm flex align-items-center justify-content-center" @click="count--"></Button>
  </div>
</template>

<style lang="scss" scoped>
.counter {
  label {
    padding-right: 10px;
    font-weight: bold;
  }
  .count {
  padding: 0 10px;
}
}
</style>


================================================
FILE: src/components/index.ts
================================================
import ComponentA from './ComponentA.vue'
import ComponentB from './ComponentB.vue'

export {
  ComponentA,
  ComponentB
}


================================================
FILE: src/constants/MyConstants.ts
================================================
export const MAGIC_NUM = 100


================================================
FILE: src/constants/index.ts
================================================
import * as MyConstants from './MyConstants'

export {
  MyConstants
}


================================================
FILE: src/env.d.ts
================================================
/// <reference types="vite/client" />

declare module '*.vue' {
  import { DefineComponent } from 'vue'
  // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/ban-types
  const component: DefineComponent<{}, {}, any>
  export default component
}


================================================
FILE: src/index.ts
================================================
import { App } from 'vue'
import * as components from './components'

function install (app: App) {
  for (const key in components) {
    // @ts-expect-error
    app.component(key, components[key])
  }
}

import './assets/main.scss'

export default { install }

export * from './components'
export * from './constants'
export * from './utils'


================================================
FILE: src/utils/MyUtil.ts
================================================
function add(a: number, b: number): number {
  return a + b;
}

export default {
  add,
};


================================================
FILE: src/utils/index.ts
================================================
import MyUtil from './MyUtil'

export {
  MyUtil
}


================================================
FILE: tsconfig.json
================================================
{
  "compilerOptions": {
    "target": "esnext",
    "useDefineForClassFields": true,
    "module": "esnext",
    "moduleResolution": "node",
    "strict": true,
    "jsx": "preserve",
    "sourceMap": true,
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "lib": ["esnext", "dom"],
    "declaration": true,
    "emitDeclarationOnly": true,
    "declarationDir": "./dist/types",
    "isolatedModules": true,
    "skipLibCheck": true,
    "types": [
      "vite/client"
    ]
  },
  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.tsx", "src/**/*.vue", "src/index.js"]
}


================================================
FILE: vite.config.ts
================================================
const path = require('path');
const { defineConfig } = require('vite');
import vue from '@vitejs/plugin-vue';

module.exports = defineConfig({
  plugins: [vue()], // to process SFC
  build: {
    lib: {
      entry: path.resolve(__dirname, 'src/index.ts'),
      name: 'my-lib',
      formats: ['es'], // adding 'umd' requires globals set to every external module
      fileName: (format) => `my-lib.${format}.js`,
    },
    rollupOptions: {
      // external modules won't be bundled into your library
      external: ['vue', /primevue\/.+/], // not every external has a global
      output: {
        // disable warning on src/index.ts using both default and named export
        exports: 'named',
        // Provide global variables to use in the UMD build
        // for externalized deps (not useful if 'umd' is not in lib.formats)
        globals: {
          vue: 'Vue',
        },
      },
    },
    emptyOutDir: false, // to retain the types folder generated by tsc
  },
});