Component Library Starter

This is a starter structure for creating a component library.

Index

• Component Library Starter
  • Index
  • Getting started
    • Development
    • Deployment
    • Once deployed
    • Importing into another project
      • Importing - Example
  • Structure
    • Component Types
      • Component Types - Example
    • Prefix
    • How to use
    • Errors

Getting started

1. Clone this repo.

2. Rename the package name in package.json. Make sure to leave the organisation name as is (@bsky/) to keep out packages within the organisation. eg

   {
     name: @bsky/headers,
     ...
   }

3. install all of the dependencies with npm install

4. Remove unused components from components directory and components index

Development

To start developing the library run npm run dev or npm start and build the components in a single file component structure.

Deployment

To deploy, merge into the master/main branch (this can be configured in the publish_to_npm.yml workflow file).

Deployment can also be run manually from the actions tab. See Manually running a workflow - Github Actions Docs

Once deployed

If this project has already been published to npm then it would be wise to start using feature branches for new components and mergin with pull requests via github.

Importing into another project

To import this into another project, simply run npm insatll @bsky/{library_name} --save and then insert import libraryName from "@bsky/library_name" and add it to your vue projects main.js

Importing - Example

// Example simple main.js =================================
import { createApp } from 'vue'
import App from './App.vue'
import BskHeaders from "@bsk-test/headers"; // Import here

createApp(App)
  .use(BskHeaders) // Use here
  .mount('#app')

Structure

Component Types

While developing components for a library you will find that there are 2 types of components

• Private components - Not usable in parent projects
• Public components - Usable in parent projects

Both of these export in some way, but only public components can be used directly by the parent project. They will still be exported but will only be used within other components.

Component Types - Example

If you have header with some icons in it, the icons can remain private as they are only split into seperate files for a more effective structure.

This way they are more encapsulated which prevents conflics with other libraries that may have another component with the same name.

Prefix

Namespace all public components with the Bsk prefix so there is minimal room for clashing component names.

How to use

All public components mus be added into the src/components/index.js file. If they aren't added, they wont be exported to the library.

Merging/pushing your changes into the master/main branch on github will automatically build the library and push it up to npm.

The progress of this can be seen in the actions tab in the github repo as 'Build and Publish to NPM registry'.

Errors

If you come accross some errors when pushing to github, the console should tell you potential reasons and how to fix them.

At the moment only versioning issues are tested for which can usually be fixed by changing the version number in the package.json to make sure that the version number is the newest.

Otherwise it may be that there is no package published under the name that you give it and the first publish will have to be done manually by running npm run build and npm publish.

if this is no longer an error and the output messege is changed to

✅ Version Number Check: Passed ..................................
   Package not yet published on NPM 

rather than

 ⛔ Version Number Check: Failed ..................................
 💔 Possible causes:
      - Package not yet published on NPM 
 🔨 To Fix:
      - Make sure package with name '{package-name}' is published to NPM

becuase I found a way to automatically publish the package please fix this in this documentation or send me (James Manning) a slack messege so I can update this.)