cja-phoenix v0.13.1

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 for more details.

# 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 stories in src/stories folder.

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

• In the root folder of this library, run npm run build:link. This will build the library for development and create a symbolic link to the library.
• In the package.json of the client app add the script: reload: npm link cja-phoenix && npm run serve, this will grab the symbolic link created by running npm run build:link.
• You can now import cja-phoenix in your client app.
• The library can be installed on your app with the App.use() function

If you made changes to the library, you will need to run npm run build:link on Phoenix's side and npm run reload on the client app's side.

It is advised to add the script "reset:packages": "npm unlink cja-phoenix && npm i cja-phoenix@latest"to the client app in order to make the process of clearing the npm link and updating the cja-phoenix version easier. Simply run it after you have made your changes and published them, the script will automatically clean up the package lock file and reinstall the latest cja-phoenix version.

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. The install function in index.ts registers all components under components to Vue globaly.

The doc app itself is a client app of the libary. The configuration in docs/.vitepress/config.js below forces VitePress to resolve vue with no duplication, avoiding errors at runtime.

module.exports = {
  vite: {
    resolve: {
      dedupe: ["vue"],
    },
  },
};

:warning: When developing components, always import library resources directly from their source files.

// Do this
import CjaButton from "../components/structural/CjaButton.vue";

// Instead of this
import { CjaButton } from "../components";

This is due to the 07/2023 Histoire Incident, during which histoire build would fail during action runtime on github due to an unclear compiler error:

Failed to load "./jsonReviver" imported from /home/runner/work/phoenix/phoenix/src/utils/index.ts

If you feel confident enough to try and resolve this issue be aware that the error may change its starting point. Good luck! :star:

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

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, the processed styles are also included into dist/style.css.

If you have your own special set of SVG icons, you may create a font file (.woff format) using tools like Icomoon or Fontello. Vite will include the font file into the build, see https://vitejs.dev/guide/assets.html.

The client app must import style.css in its entry file:

import "cja-phoenix/style.css";

Any additional styles (such as Tippy's or intl-tel-input) must be imported manually in the consuming app's entry file

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 can externalize the dependency. For example, to exclude Vue from your library build artifact, in vite.config.ts, you can have

module.exports = defineConfig({
    rollupOptions: {
      external: ['vue']
    }
  }
})

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

Nuxt Apps

The library is specially adapted to be used with nuxt apps and as such requires specific configurations.

Library Initialization

When attaching the library to the app, you must provide the use function with an options object containing urls for the image cdn, api url and if needed provider image url.

Standard Vue Apps

As development on the library progresses, the code has been adapted to cater to nuxt requirements and specific patterns. Nevertheless, if the library must be used on standalone vue apps, additional steps must be taken.

Library Initialization

When attaching the library to the app, the additional options do not work properly within the instance context. Instead, process env variables must be made available for library components to work properly:

VUE_APP_IMG_URL (images cdn) VUE_APP_API_URL (requests url) VUE_APP_PROVIDERS_IMG_URL (providers images cdn)

Importing SCSS variables

Add the following code to vue.config in order to import the library SCSS variables

css: {
  loaderOptions: {
    scss: {
      additionalData: `@import "cja-phoenix/variables.scss";`,
    },
  },
}

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, enabling this option leads to https://github.com/vitejs/vite/issues/5814. The workaround is to also enable compilerOptions.skipLibCheck.

"compilerOptions": {
  "isolatedModules": true
}

In tsconfig.json, set the following to address Issue #32. The solution is from https://github.com/johnsoncodehk/volar/discussions/592.

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

Dependencies

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