Stagedates Frontend Components

ToDO

Setup

# install dependencies
npm install

# Start storybook for development
npm run storybook

# Generate storybook for deployment
npm run storybook:generate

# build the library, available under dist
npm run build

Publish package

1. Create a release branch with the new version number as name.
2. Increase version number in package.json according to semantic versioning and commit the files.
3. Create pull requests to master and develop branches.
4. After merge run npm publish from the master branch to publish the new package.

Develop and test 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 stagedates-frontend-components. This will add the symbolic link to the node_modules folder in your client app.
• You can now import stagedates-frontend-components in your client app.

There is no need to add stagedates-frontend-components 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. The install function in index.ts registers all components under components to Vue globably.

The components are also exported by 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 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. The configuration in 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.

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

In 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. The client app may use them as below:

<script lang="ts">
import { MyConstants, MyUtil } from 'stagedates-frontend-components'

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.

If you have library level styles shared by all components in the library, you may add them to src/assets/main.scss. This file is imported in 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.

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

import 'stagedates-frontend-components/dist/styles.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.

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, you may have

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

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

Type generation

In 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.

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

In package.json, the line below locates the generated types for library client.

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

In 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, 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.

"compilerOptions": {
  "isolatedModules": true
}