berryjam v0.1.0-alpha.64

:book: Table of Contents

1. Why Berryjam
2. Features
3. Limitations
4. Getting Started
5. Development
6. Contributing
7. Need Help?
8. License
9. Acknowledgement

:star: Why Berryjam

Berryjam provides a simple way to identify your component usage, props and their relationships. Based on the output from your scan, you can create your own dashboard and run analysis across your project components to improve communications across your development team.

:sparkles: Features

:see_no_evil: Limitations

• Berryjam is not compatible with Vue 2 or lower versions.

• Berryjam has been fully tested to work with node version from 16.0 to 18.17.1 (LTS). Versions above 18.17.1 (LTS) should work as well but have not been fully tested.

:rocket: Getting Started

Install Berryjam

There are a few ways you can install Berryjam, namely npm, pnpm and yarn. If you install via npm, here is a single cmd to install this library

  npm install berryjam

Other options

• pnpm

  pnpm add berryjam

• yarn

  yarn add berryjam

Usage

To start scanning your project, you will first need to import VueScanner class and create its instance.

import { homedir } from 'os';
import VueScanner from "berryjam"
import type { VueScannerOption, ComponentProfile } from "berryjam"
...
const pathToScan = '../your-vue-project-path';
const option: VueScannerOption = {
  // this folder will be used to store the exact versions of babel & vue compiler
  appDir: `${homedir()}/.vueScanner`,
  // ... any other options
}
// Create a new VueScanner instance with the required parameters
const vueScanner = new VueScanner(pathToScan, option);
...
// To start scanning without async/await
vueScanner.scan().then(result => {
  // the result will be an array of ComponentProfile
  // log to see the result
  console.log(result);
})

// or, You can use async/await
async function whatEverFunction() {
  const result = await vueScanner.scan();
}

Note: For a Nuxt project, please ensure that you have a .nuxt folder before scanning.

The VueScanner function takes two parameters as follow:

• The first parameter is the path of the project to be scanned.
• The second is an option object that utilizes the VueScannerOption interface.

Here is the detailed description of each available option within the VueScannerOption interface:

VueScannerOption Interface

OutputFormat Type

The OutputFormat type represents available output formats.

These options and types offer flexibility and customization when using the VueScanner function to analyze Vue.js projects.

For more details on VueScanner class, please check out below.

Output

By calling the scan method, it will scan for Vue components and return ComponentProfile[]. Here is an example of how it may look. For demonstration purposes, we have scanned an open-source project called Koel.

[
  {
    "name": "PlaybackControls",
    "type": "internal",
    "total": 1,
    "source": {
      "path": "/resources/assets/js/components/layout/app-footer/FooterPlaybackControls.vue",
      "property": {
        "dataLastModified": "Sun Feb 04 2018",
        "lastModified": "Sun Feb 04 2018",
        "created": "2018-02-02T21:12:19.000Z",
        "createdBy": "Phan An",
        "updatedBy": "Phan An"
      }
    },
    "usageLocations": [
      {
        "name": "PlaybackControls",
        "source": "/resources/assets/js/components/layout/app-footer/FooterPlaybackControls.vue",
        "destination": "/resources/assets/js/components/layout/app-footer/index.vue",
        "rows": [
          9
        ],
        "fileInfo": {
          "path": "/resources/assets/js/components/layout/app-footer/FooterPlaybackControls.vue",
          "property": {
            "dataLastModified": "Sun Feb 04 2018",
            "lastModified": "Sun Feb 04 2018",
            "created": "2018-02-02T21:12:19.000Z",
            "createdBy": "Phan An",
            "updatedBy": "Phan An"
          }
        }
      }
    ],
    "children": {
      "total": 4,
      "tags": [
        "LikeButton",
        "icon",
        "PlayButton",
        "RepeatModeSwitch"
      ],
      "source": "/resources/assets/js/components/layout/app-footer/FooterPlaybackControls.vue"
    }
  },
  {
    "name": "PlayButton",
    "type": "internal",
    "total": 1,
    "source": {
      "path": "/resources/assets/js/components/ui/FooterPlayButton.vue",
      "property": {
        "dataLastModified": "Sun Feb 04 2018",
        "lastModified": "Sun Feb 04 2018",
        "created": "2018-02-02T21:12:19.000Z",
        "createdBy": "Phan An",
        "updatedBy": "Phan An"
      }
    },
    "usageLocations": [
      {
        "name": "PlayButton",
        "source": "/resources/assets/js/components/ui/FooterPlayButton.vue",
        "destination": "/resources/assets/js/components/layout/app-footer/FooterPlaybackControls.vue",
        "rows": [
          11
        ],
        "fileInfo": {
          "path": "/resources/assets/js/components/ui/FooterPlayButton.vue",
          "property": {
            "dataLastModified": "Sun Feb 04 2018",
            "lastModified": "Sun Feb 04 2018",
            "created": "2018-02-02T21:12:19.000Z",
            "createdBy": "Phan An",
            "updatedBy": "Phan An"
          }
        }
      }
    ],
    "children": {
      "total": 1,
      "tags": [
        "icon"
      ],
      "source": "/resources/assets/js/components/ui/FooterPlayButton.vue"
    }
  },
]

:construction: Development

The library uses Nodejs, TypeScript and Jest for development. Since this is a tool for detecting Vue components, you may find the rules on how Vue components in the built-in-rules folder.

How It Works

Berryjam contains 2 classes, namely:

1. VueScanner - Use to scan a project for component profiles. It will extract relevant relative values such as source, file path, component name from package.json files and their respective supported files to transform or normalize raw component data which will be mapped to each component profile.

2. GitService - If the project has .git folder, it will look for git related information such as author and datetime and map to each component profile.

VueScanner Overview

Within the VueScanner class, you may call on scan() method to start scanning. The method encompasses 5 main steps. There are as follow:

GitService Overview

Below are the main methods in the GitService class:

Dependencies

Third-Party plugins are loaded automatically from Berryjam’s package.json

• Code Parsers
  • Babel
  • Vue
• Node Modules
  • path
  • fs
• Others
  • glob
  • lodash
  • tsconfig-paths

For more information, please refer to the documentation folder.

:muscle: Contributing

We are thankful and appreciative for all types of contributions. Whether you are helping us report or fix bugs, proposing new features, improving our documentation or spreading the word - we would love to have you as a part of the Berryjam community. Please refer to our Contributing Guide and Code of Conduct.

If you wish to start contributing right away, navigate to the GitHub Issues tab and start looking through interesting issues. You may start off by working on issues labeled under documentation and good first issue.

If you run into an error or an issue while using Berryjam, you have an idea on how to better Berryjam or perhaps you are looking through the documentation and thinking that it could be improved... please don’t hesitate to submit an issue :sunglasses:

If you are a Vue.js developer who is not familiar with Node.js., you can submit an issue labeled code example on how you create Vue components. Check out our built-in-rules for more details.

:raising_hand: Need Help?

We are more than happy to help you. If you have any questions, run into any errors or face any problems, please feel free to ask for help in Berryjam Discord. Anything related to Berryjam is on the table!

:page_facing_up: License

Berryjam is distributed under MIT License. Please refer to our LICENSE.md file for more details.

Acknowledgement

• Babel
• Glob
• Img Shields
• lodash
• Node.js
• Tsconfig-Paths
• Vue.js