Add usage example, fix build for use with bundlers and browser (#552)

Co-authored-by: Sergiu Cazac <kilobyte2007@gmail.com>

Author: JosephusPaye

.github/workflows/node.js.yml

@@ -27,8 +27,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
-        node-version: [14.x, 16.x, 18.x]
+        node-version: [lts/*] # latest LTS version of Node
     steps:
       - uses: actions/checkout@v3
       - name: Use Node.js ${{ matrix.node-version }}

build/build.lib.mjs

@@ -38,6 +38,9 @@ const entries = [
   "UiTooltip",
 ];
 
+// We need to get the env variable here because it later gets polluted by child processes
+const mode = process.env.NODE_ENV || "production";
+
 entries.forEach(async (entry) => {
-  await build(getLibConfig({ entry, mode: process.env.NODE_ENV || "production" }));
+  await build(getLibConfig({ entry, mode }));
 });

build/vite.config.dist.mjs

@@ -6,9 +6,20 @@ import autoprefixer from "autoprefixer";
 import options from "./options.mjs";
 
 export default defineConfig(({ mode }) => {
-  const filename = mode === "production" ? "keen-ui.min" : "keen-ui";
+  const isProduction = mode === "production";
   const outDir = options.paths.output.main;
 
+  const formatFileNames = {
+    es: {
+      development: "keen-ui.esm.js",
+      production: "keen-ui.esm.min.js",
+    },
+    umd: {
+      development: "keen-ui.js",
+      production: "keen-ui.min.js",
+    },
+  };
+
   return {
     plugins: [vue(), banner({ content: options.banner, outDir })],
     resolve: {
@@ -31,14 +42,19 @@ export default defineConfig(({ mode }) => {
       lib: {
         entry: options.paths.resolve("src/index.js"),
         name: "KeenUI",
-        formats: ["umd"],
-        fileName: () => filename + ".js",
+        formats: isProduction ? ["umd"] : ['umd', 'es'],
+        fileName: (format) => {
+          return formatFileNames[format][mode]
+        },
       },
       rollupOptions: {
         external: [/^vue/],
         output: {
+          globals: {
+            vue: "Vue",
+          },
           assetFileNames: (assetInfo) =>
-            assetInfo.name === "style.css" ? filename + ".css" : assetInfo.name,
+            assetInfo.name === "style.css" ? `keen-ui${isProduction ? '.min' : ''}.css` : assetInfo.name,
         },
       },
     },

build/vite.config.lib.provider.mjs

@@ -5,8 +5,20 @@ import autoprefixer from "autoprefixer";
 import options from "./options.mjs";
 
 export default ({ entry, mode }) => {
+  const isProduction = mode === "production";
   const outDir = options.paths.output.lib;
 
+  const formatFileNames = {
+    es: {
+      development: `${entry}.esm.js`,
+      production: `${entry}.esm.min.js`,
+    },
+    umd: {
+      development: `${entry}.js`,
+      production: `${entry}.min.js`,
+    },
+  };
+
   return {
     plugins: [vue(), banner({ content: options.banner, outDir })],
     resolve: {
@@ -20,11 +32,13 @@ export default ({ entry, mode }) => {
       },
     },
     build: {
-      minify: mode === "production" ? "esbuild" : false,
+      minify: isProduction ? "esbuild" : false,
       lib: {
         entry: options.paths.resolve(`src/${entry}.vue`),
-        formats: ["umd"],
-        fileName: () => `[name]${mode === "production" ? ".min" : ""}.js`,
+        formats: isProduction ? ["umd"] : ['umd', 'es'],
+        fileName: (format) => {
+          return formatFileNames[format][mode]
+        },
         name: `KeenUI.${entry}`,
       },
       outDir,
@@ -36,6 +50,9 @@ export default ({ entry, mode }) => {
           globals: {
             vue: "Vue",
           },
+          assetFileNames: () => {
+            return `css/[name][extname]`
+          }
         },
       },
     },

dist/keen-ui.css

@@ -2,7 +2,23 @@
   "name": "keen-ui",
   "version": "1.4.0",
   "description": "Keen UI is a Vue.js UI library with a simple API, inspired by Google's Material Design.",
-  "main": "dist/keen-ui.js",
+  "main": "./dist/keen-ui.js",
+  "module": "./dist/keen-ui.esm.js",
+  "exports": {
+    ".": {
+      "import": "./dist/keen-ui.esm.js",
+      "require": "./dist/keen-ui.js"
+    },
+    "./keen-ui.css": "./dist/keen-ui.css",
+    "./src/*": {
+      "import": "./src/*"
+    },
+    "./css/*": "./lib/css/*",
+    "./*": {
+      "import": "./lib/*.esm.js",
+      "require": "./lib/*.js"
+    }
+  },
   "scripts": {
     "dev": "vite serve --config build/vite.config.docs.mjs docs-src",
     "build:dist": "vite build --config build/vite.config.dist.mjs --mode development",

dist/keen-ui.esm.js

@@ -74,7 +74,7 @@ const KeenUI = {
   UiTooltip,
 };
 
-KeenUI.install = function (app, config = {}) {
+export function install(app, config = {}) {
   // Configure the component props
   Object.keys(config).forEach((key) => {
     if (startsWith(key, "Ui")) {
@@ -96,15 +96,8 @@ KeenUI.install = function (app, config = {}) {
       app.component(Component.name, Component);
     }
   });
-};
-
-// Make Keen UI available globally when in a browser environment
-if (typeof window !== "undefined") {
-  window.KeenUI = KeenUI;
 }
 
-export default KeenUI;
-
 export {
   UiAlert,
   UiAutocomplete,
@@ -141,3 +134,8 @@ export {
   UiToolbar,
   UiTooltip,
 };
+
+export default {
+  ...KeenUI,
+  install,
+};

dist/keen-ui.js

@@ -0,0 +1,11 @@
+# Keen UI static usage example
+
+This is an example of using Vue + Keen UI via global script tags, without a build system like Vite or Webpack.
+
+## Usage
+
+- From the Keen UI root directory:
+  - Run `yarn` to install dependencies
+  - Run `yarn build:dist && yarn build:dist:prod` to build the library
+- From this `usage-example-static` directory:
+  - Open the `index.html` file in your browser. If it's working you should see a message and some styled buttons.

package.json

@@ -0,0 +1,39 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Keen UI Static Usage Example</title>
+    <script src="https://unpkg.com/vue@3/dist/vue.global.prod.js"></script>
+    <script src="../dist/keen-ui.min.js"></script>
+    <link rel="stylesheet" href="../dist/keen-ui.min.css" type="text/css" />
+  </head>
+  <body>
+    <div id="app" style="text-align: center">
+      <div>{{ message }}</div>
+      <br />
+      <ui-button>Button from Keen UI plugin</ui-button>
+      <br />
+      <br />
+      <my-button>Button from component registration</my-button>
+    </div>
+
+    <script>
+      const { createApp } = Vue;
+      const app = createApp({
+        data() {
+          return {
+            message: "Hello from Vue!",
+          };
+        },
+      });
+
+      // Works as a plugin
+      app.use(KeenUI);
+
+      // Also we can use separate components
+      app.component("my-button", KeenUI.UiButton);
+
+      app.mount("#app");
+    </script>
+  </body>
+</html>

src/index.js

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

usage-example-static/README.md

@@ -0,0 +1,18 @@
+# Keen UI Vite usage example
+
+This is an example Vite project to test the usage of Keen UI:
+
+- using the default export and named exports
+- using lib exports
+- using the Keen UI `.vue` source files directly
+
+## Usage
+
+- From the Keen UI root directory:
+  - Run `yarn` to install dependencies
+  - Run `yarn build:all && yarn build:all:prod` to build the library
+  - Run `yarn link`
+- From this `usage-example-vite` directory:
+  - Run `yarn` to install dependencies
+  - Run `yarn link keen-ui` to link the local Keen UI build to the example project
+  - Run `yarn dev` to start Vite and visit the URL shown to view the example

usage-example-static/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite + Vue</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

usage-example-vite/.gitignore

@@ -0,0 +1,18 @@
+{
+  "name": "usage-test",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "vue": "^3.2.45"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^4.0.0",
+    "vite": "^4.0.0"
+  }
+}

usage-example-vite/README.md

@@ -0,0 +1,20 @@
+<script setup>
+import UsesDefaultExport from './components/UsesDefaultExport.vue';
+import UsesNamedExport from './components/UsesNamedExport.vue';
+import UsesSrcExport from './components/UsesSrcExport.vue';
+import UsesLibExport from './components/UsesLibExport.vue';
+</script>
+
+<template>
+  <div>
+    <p>The following should be styled Keen UI buttons if the imports are working:</p>
+    <br />
+    <UsesDefaultExport />
+    <br />
+    <UsesNamedExport />
+    <br />
+    <UsesSrcExport />
+    <br />
+    <UsesLibExport />
+  </div>
+</template>

usage-example-vite/index.html

@@ -0,0 +1,10 @@
+<script setup>
+import * as KeenUI from 'keen-ui';
+import 'keen-ui/keen-ui.css';
+</script>
+
+<template>
+  <div>
+    <KeenUI.UiButton>Uses Default Export</KeenUI.UiButton>
+  </div>
+</template>

usage-example-vite/package.json

@@ -0,0 +1,10 @@
+<script setup>
+import UiButton from 'keen-ui/UiButton';
+import 'keen-ui/css/UiButton.css';
+</script>
+
+<template>
+  <div>
+    <UiButton>Uses Lib Export</UiButton>
+  </div>
+</template>

usage-example-vite/public/vite.svg

@@ -0,0 +1,10 @@
+<script setup>
+import { UiButton } from 'keen-ui';
+import 'keen-ui/keen-ui.css';
+</script>
+
+<template>
+  <div>
+    <UiButton>Uses Named Export</UiButton>
+  </div>
+</template>

usage-example-vite/src/App.vue

@@ -0,0 +1,7 @@
+<script setup>
+import UiButton from 'keen-ui/src/UiButton.vue';
+</script>
+
+<template>
+  <div><UiButton>Uses Src Export</UiButton></div>
+</template>

usage-example-vite/src/components/UsesDefaultExport.vue

@@ -0,0 +1,7 @@
+import { createApp } from 'vue'
+
+import './style.css'
+
+import App from './App.vue'
+
+createApp(App).mount('#app')

usage-example-vite/src/components/UsesLibExport.vue

@@ -0,0 +1,9 @@
+* {
+  box-sizing: border-box;
+}
+
+:root {
+  font-family: system-ui, sans-serif;
+  font-size: 16px;
+  text-align: center;
+}

usage-example-vite/src/components/UsesNamedExport.vue

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [vue()],
+})