Cja-phoenix NPM

CJA Phoenix

Setup

# install dependencies
npm install

# start the doc app, great for testing components
npm run story:dev

# build the doc app for deployment
npm run story:build

# build the library, available under dist
npm run build

# build the library for use with npm link
npm run build:link

# builds the library for publishing, requires a version bump
npm run publish:lib

Develop and test locally

The best way to develop and test your component is by creating stories in src/histoire 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

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

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.

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

import "cja-phoenix/style";

Iconia

In order to edit the Iconia font access Icomoon and perform the required adaptations. If the current Iconia project is not loaded, use the import project tool with the assets/iconia/selection.json file. In order to properly generate the font svg file inputs should have outlined strokes. General rule, icons should have their size scaled up to the canvas and color removed through the edit function.

After editing the font, the types/Icon.ts file should be updated to include the new icon class names.

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.

Importing SCSS variables

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

css: {
  loaderOptions: {
    scss: {
      additionalData: `@use "cja-phoenix/variables" as *;`,
    },
  },
}

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.