cja-phoenix 0.0.1

package/README.md

@@ -0,0 +1,178 @@
+# CJA Phoenix
+
+## 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. 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:lib
+
+# 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
+```
+
+## Develop and test locally
+
+The best way to develop and test your component is by creating demos in `docs/components/demo` folder.
+
+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 cja-phoenix`. This will add the symbolic link to the `node_modules` folder in your client app.
+- You can now import `cja-phoenix` in your client app.
+
+There is no need to add `cja-phoenix` 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 will hot reload when the building of library is completed.
+
+## Publishing
+
+After testing your developments and updating the documentation app, bump the version in `package.json` and run `npm run publish:lib`
+
+## 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 globaly.
+
+The doc app itself is a client app of the libary. The configuration in [docs/.vitepress/config.js](docs/.vitepress/config.js) below forces VitePress to resolve vue with no duplication, avoiding errors at runtime.
+
+```js
+module.exports = {
+  vite: {
+    resolve: {
+      dedupe: ["vue"],
+    },
+  },
+};
+```
+
+> In [vite.config.ts](vite.config.ts), format 'umd' is not present in `build.lib.formats` option.
+
+### 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 'cja-phoenix'
+
+export default {
+  data () {
+    return {
+      magicNum: MyConstants.MAGIC_NUM
+    }
+  },
+  methods: {
+    add (a:number, b:number) {
+      return MyUtil.add(a, b)
+    }
+  }
+}
+</script>
+```
+
+### Styling
+
+Individual components 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), 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. 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 imports `style.css`, usually in the entry file:
+
+```js
+import "cja-phoenix/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 can externalize the dependency. For example, to exclude Vue from your library build artifact, in [vite.config.ts](vite.config.ts), you can have
+
+```js
+module.exports = defineConfig({
+    rollupOptions: {
+      external: ['vue']
+    }
+  }
+})
+```
+
+The dependency to be externalized can be declared as a peer dependency in your library.
+
+#### Cherry picking
+
+If you don't expect the client app of your library to also need 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 the 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, enabling 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"
+  ]
+}
+```
+
+#### Dependencies
+
+In [package.json](package.json), Vue is declared in both `peerDependencies` and `devDependencies`. The former requires the client app to add these dependencies, and the later makes it easier to setup this library by simply running `npm install`.

package/dist/cja-phoenix.es.js

@@ -0,0 +1,79 @@
+import { defineComponent, openBlock, createElementBlock, createTextVNode, toDisplayString, pushScopeId, popScopeId, createElementVNode, ref } from "vue";
+var ComponentA_vue_vue_type_style_index_0_scoped_true_lang = "";
+var _export_sfc = (sfc, props) => {
+  const target = sfc.__vccOpts || sfc;
+  for (const [key, val] of props) {
+    target[key] = val;
+  }
+  return target;
+};
+const _withScopeId$1 = (n) => (pushScopeId("data-v-5800c09e"), n = n(), popScopeId(), n);
+const _hoisted_1$1 = { class: "component-a-container" };
+const _hoisted_2$1 = /* @__PURE__ */ _withScopeId$1(() => /* @__PURE__ */ createElementVNode("span", { class: "icon-heart" }, null, -1));
+const _sfc_main$1 = /* @__PURE__ */ defineComponent({
+  props: {
+    msg: null
+  },
+  setup(__props) {
+    return (_ctx, _cache) => {
+      return openBlock(), createElementBlock("div", _hoisted_1$1, [
+        createTextVNode(" Hello " + toDisplayString(__props.msg) + "! ", 1),
+        _hoisted_2$1
+      ]);
+    };
+  }
+});
+var ComponentA = /* @__PURE__ */ _export_sfc(_sfc_main$1, [["__scopeId", "data-v-5800c09e"]]);
+var ComponentB_vue_vue_type_style_index_0_scoped_true_lang = "";
+const _withScopeId = (n) => (pushScopeId("data-v-2c22e62b"), n = n(), popScopeId(), n);
+const _hoisted_1 = { class: "flex align-content-center flex-wrap counter" };
+const _hoisted_2 = /* @__PURE__ */ _withScopeId(() => /* @__PURE__ */ createElementVNode("label", { class: "flex align-items-center justify-content-center" }, "Counter:", -1));
+const _hoisted_3 = { class: "flex align-items-center justify-content-center count" };
+const _sfc_main = /* @__PURE__ */ defineComponent({
+  setup(__props) {
+    const count = ref(0);
+    return (_ctx, _cache) => {
+      return openBlock(), createElementBlock("div", _hoisted_1, [
+        _hoisted_2,
+        createElementVNode("button", {
+          icon: "pi pi-plus",
+          class: "p-button-sm flex align-items-center justify-content-center",
+          onClick: _cache[0] || (_cache[0] = ($event) => count.value++)
+        }),
+        createElementVNode("span", _hoisted_3, toDisplayString(count.value), 1),
+        createElementVNode("button", {
+          icon: "pi pi-minus",
+          class: "p-button-sm flex align-items-center justify-content-center",
+          onClick: _cache[1] || (_cache[1] = ($event) => count.value--)
+        })
+      ]);
+    };
+  }
+});
+var ComponentB = /* @__PURE__ */ _export_sfc(_sfc_main, [["__scopeId", "data-v-2c22e62b"]]);
+var components = /* @__PURE__ */ Object.freeze({
+  __proto__: null,
+  [Symbol.toStringTag]: "Module",
+  ComponentA,
+  ComponentB
+});
+var main = "";
+const MAGIC_NUM = 100;
+var MyConstants = /* @__PURE__ */ Object.freeze({
+  __proto__: null,
+  [Symbol.toStringTag]: "Module",
+  MAGIC_NUM
+});
+function add(a, b) {
+  return a + b;
+}
+var MyUtil = {
+  add
+};
+function install(app) {
+  for (const key in components) {
+    app.component(key, components[key]);
+  }
+}
+var index = { install };
+export { ComponentA, ComponentB, MyConstants, MyUtil, index as default };

package/dist/style.css

@@ -0,0 +1 @@
+.icon-heart[data-v-5800c09e]{color:tomato}.counter label[data-v-2c22e62b]{padding-right:10px;font-weight:700}.counter .count[data-v-2c22e62b]{padding:0 10px}@font-face{font-family:myfont;src:url(data:font/woff;base64,d09GRgABAAAAAATMAAsAAAAABIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABPUy8yAAABCAAAAGAAAABgDxIGBGNtYXAAAAFoAAAAVAAAAFQWfNQ7Z2FzcAAAAbwAAAAIAAAACAAAABBnbHlmAAABxAAAAMQAAADE9iu5ZGhlYWQAAAKIAAAANgAAADYfdnyraGhlYQAAAsAAAAAkAAAAJAfCA8ZobXR4AAAC5AAAABQAAAAUCgAAAGxvY2EAAAL4AAAADAAAAAwAKAB2bWF4cAAAAwQAAAAgAAAAIAAHACxuYW1lAAADJAAAAYYAAAGGmUoJ+3Bvc3QAAASsAAAAIAAAACAAAwAAAAMDAAGQAAUAAAKZAswAAACPApkCzAAAAesAMwEJAAAAAAAAAAAAAAAAAAAAARAAAAAAAAAAAAAAAAAAAAAAQAAA6doDwP/AAEADwABAAAAAAQAAAAAAAAAAAAAAIAAAAAAAAwAAAAMAAAAcAAEAAwAAABwAAwABAAAAHAAEADgAAAAKAAgAAgACAAEAIOna//3//wAAAAAAIOna//3//wAB/+MWKgADAAEAAAAAAAAAAAAAAAEAAf//AA8AAQAAAAAAAAAAAAIAADc5AQAAAAABAAAAAAAAAAAAAgAANzkBAAAAAAEAAAAAAAAAAAACAAA3OQEAAAAAAQAA/8wEAAOAACkAAAEiBw4BBwYHJicuAScmIyIHDgEHBhUUFx4BFxYXNjc+ATc2NTQnLgEnJgLzKCUlPxkZEBAZGT8lJSg4MTFJFRUzM5lZWk5KWVmbNTQVFUkxMQOADw8yICEiIiEgMg8PFRVJMTE4cU5Pjk5NcG9PT5BOT204MTFJFRUAAAEAAAAAAABxV9/FXw889QALBAAAAAAA3iwcMQAAAADeLBwxAAD/zAQAA4AAAAAIAAIAAAAAAAAAAQAAA8D/wAAABAAAAAAABAAAAQAAAAAAAAAAAAAAAAAAAAUEAAAAAAAAAAAAAAACAAAABAAAAAAAAAAACgAUAB4AYgABAAAABQAqAAEAAAAAAAIAAAAAAAAAAAAAAAAAAAAAAAAADgCuAAEAAAAAAAEABwAAAAEAAAAAAAIABwBgAAEAAAAAAAMABwA2AAEAAAAAAAQABwB1AAEAAAAAAAUACwAVAAEAAAAAAAYABwBLAAEAAAAAAAoAGgCKAAMAAQQJAAEADgAHAAMAAQQJAAIADgBnAAMAAQQJAAMADgA9AAMAAQQJAAQADgB8AAMAAQQJAAUAFgAgAAMAAQQJAAYADgBSAAMAAQQJAAoANACkaWNvbW9vbgBpAGMAbwBtAG8AbwBuVmVyc2lvbiAxLjAAVgBlAHIAcwBpAG8AbgAgADEALgAwaWNvbW9vbgBpAGMAbwBtAG8AbwBuaWNvbW9vbgBpAGMAbwBtAG8AbwBuUmVndWxhcgBSAGUAZwB1AGwAYQByaWNvbW9vbgBpAGMAbwBtAG8AbwBuRm9udCBnZW5lcmF0ZWQgYnkgSWNvTW9vbi4ARgBvAG4AdAAgAGcAZQBuAGUAcgBhAHQAZQBkACAAYgB5ACAASQBjAG8ATQBvAG8AbgAuAAAAAwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==)}[class^=icon-],[class*=" icon-"]{font-family:myfont!important}.icon-heart:before{content:"\e9da"}.global-example{color:red}

package/dist/types/components/ComponentA.vue.d.ts

@@ -0,0 +1,15 @@
+declare const _default: import("vue").DefineComponent<__VLS_DefinePropsToOptions<{
+    msg: string;
+}>, () => void, unknown, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, Record<string, any>, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<__VLS_DefinePropsToOptions<{
+    msg: string;
+}>>>, {}>;
+export default _default;
+declare type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
+declare type __VLS_DefinePropsToOptions<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: import('vue').PropType<__VLS_NonUndefinedable<T[K]>>;
+    } : {
+        type: import('vue').PropType<T[K]>;
+        required: true;
+    };
+};

package/dist/types/components/ComponentB.vue.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vue").DefineComponent<{}, () => void, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, import("vue").EmitsOptions, string, import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps, Readonly<import("vue").ExtractPropTypes<{}>>, {}>;
+export default _default;

package/dist/types/components/index.d.ts

@@ -0,0 +1,3 @@
+import ComponentA from './ComponentA.vue';
+import ComponentB from './ComponentB.vue';
+export { ComponentA, ComponentB };

package/dist/types/constants/MyConstants.d.ts

@@ -0,0 +1 @@
+export declare const MAGIC_NUM = 100;

package/dist/types/constants/index.d.ts

@@ -0,0 +1,2 @@
+import * as MyConstants from './MyConstants';
+export { MyConstants };

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+import { App } from "vue";
+declare function install(app: App): void;
+import "./assets/main.scss";
+declare const _default: {
+    install: typeof install;
+};
+export default _default;
+export * from "./components";
+export * from "./constants";
+export * from "./utils";

package/dist/types/utils/MyUtil.d.ts

@@ -0,0 +1,5 @@
+declare function add(a: number, b: number): number;
+declare const _default: {
+    add: typeof add;
+};
+export default _default;

package/dist/types/utils/index.d.ts

@@ -0,0 +1,2 @@
+import MyUtil from './MyUtil';
+export { MyUtil };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "cja-phoenix",
+  "version": "0.0.1",
+  "scripts": {
+    "build:lib": "rimraf dist && vue-tsc && vite build",
+    "publish:lib": "npm run build:lib && npm publish",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:serve": "vitepress serve docs"
+  },
+  "peerDependencies": {
+    "vue": "^3.2.25"
+  },
+  "devDependencies": {
+    "@types/node": "^17.0.14",
+    "@vitejs/plugin-vue": "^2.0.0",
+    "rimraf": "^3.0.2",
+    "sass": "^1.49.7",
+    "typescript": "^4.4.4",
+    "vite": "^2.7.2",
+    "vitepress": "^0.21.6",
+    "vue": "^3.2.25",
+    "vue-tsc": "^0.29.8"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "types": "./dist/types/index.d.ts",
+  "module": "./dist/cja-phoenix.es.js",
+  "exports": {
+    ".": {
+      "import": "./dist/cja-phoenix.es.js"
+    },
+    "./dist/style.css": "./dist/style.css"
+  }
+}

package/src/assets/main.scss

@@ -0,0 +1,17 @@
+@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;
+}

package/src/components/ComponentA.vue

@@ -0,0 +1,17 @@
+<template>
+  <div class="component-a-container">
+    Hello {{ msg }}! <span class="icon-heart"></span>
+  </div>
+</template>
+
+<script setup lang="ts">
+const props = defineProps<{
+  msg: string;
+}>();
+</script>
+
+<style lang="scss" scoped>
+.icon-heart {
+  color: tomato;
+}
+</style>

package/src/components/ComponentB.vue

@@ -0,0 +1,37 @@
+<script setup lang="ts">
+import { ref } from "vue";
+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>

package/src/components/index.ts

@@ -0,0 +1,7 @@
+import ComponentA from './ComponentA.vue'
+import ComponentB from './ComponentB.vue'
+
+export {
+  ComponentA,
+  ComponentB
+}

package/src/constants/MyConstants.ts

@@ -0,0 +1 @@
+export const MAGIC_NUM = 100

package/src/constants/index.ts

@@ -0,0 +1,5 @@
+import * as MyConstants from './MyConstants'
+
+export {
+  MyConstants
+}

package/src/env.d.ts

@@ -0,0 +1,8 @@
+/// <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
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+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";

package/src/utils/MyUtil.ts

@@ -0,0 +1,7 @@
+function add(a: number, b: number): number {
+  return a + b;
+}
+
+export default {
+  add,
+};

package/src/utils/index.ts

@@ -0,0 +1,5 @@
+import MyUtil from './MyUtil'
+
+export {
+  MyUtil
+}