simple-apps-components (NPM PACKAGE)

Repository Overview

• Branches
  • develop: Used for staging and testing updates. Developers push their changes here to ensure everything works as expected.
  • master: The branch that will publish to NPM. Only thoroughly tested and approved changes from develop are merged here for release.
• Directory Structure:

/dev               # Local Vue app to preview components
/src               # Component library source code
  ├── /components  # Raw components
  └── index.js     # Library entry point

Versioning Strategy

This repository uses the semver versioning strategy.

The justification for bumping each part of the version is as follows:

• Major: MAJOR changes (not using bootstrap 5, not using Vue 3, etc.)
• Minor: Breaking changes (removing/changing props, removing components, etc.)
• Patch: Non-breaking changes (adding new props, adding new components, bugfixes, etc.)

When making breaking changes, you must also create a migration guide in the wiki (gitlab).

Getting Started (Using the package)

Installation

• yarn add simple-apps-components
• All components and services contained within are available as named imports from the module index, and can be imported with the following syntax:
  • import { SimpleInput, SimpleSelect, fastApi } from 'simple-apps-components'

Getting Started (Development)

Prerequisites

• Node.js and Yarn installed globally.

Install Dependencies

yarn install

Development Workflow

Run Local Dev Environment

The /dev directory contains a Vue 3 app set up with Vite for previewing and testing components during development. To spin up the local server:

yarn dev

This will start a Vite server. Open your browser and visit http://localhost:3000 (or the port Vite provides) to see the components in action.

Adding or Modifying Components

1. Create branch off of develop
2. Add or update components inside /src/components
3. Add or update a test (see testing)
4. Ensure the component exports are correctly referenced in /src/index.js
5. Finally, send merge request for review

Testing

Vitest is used to write Unit Tests for both Vue components and any utility files.

To trigger tests, run yarn test in your terminal

Example of a Vue component test SimpleCard.spec.js:

import { mount } from '@vue/test-utils'
import SimpleCard from '../../src/components/SimpleCard.vue'

describe('SimpleCard.vue', () => {
  it('renders the body slot content', () => {
    const wrapper = mount(SimpleCard, {
      props: { title: 'Test Title' },
      slots: {
        body: '<div class="test-body">This is the body content.</div>',
      },
    })

    expect(wrapper.find('.test-body').exists()).toBe(true)
  })
})

Snapshots

Components will often utilize Snapshots to ensure that the rendered output of the components remains consistent over time. When you run a snapshot test, Vitest renders your component (or function result) and saves its output as a JSON-like string inside a __snapshots__ directory. This snapshot serves as a reference. In future test runs, Vitest compares the current output to the saved snapshot to ensure nothing has changed unexpectedly.

1. Updating Snapshots:
   • If the changes to your component are intentional (like UI updates), you can update the snapshot by running: yarn test -u or vitest run -u
2. Deleting Snapshots:
   • You don't need to delete them unless they are associated with outdated tests or components you've removed. If a test no longer exists, Vitest will inform you about unused snapshots when you run the tests.
3. Version Control:
   • Snapshots should be added to Gitlab. This allows other team members to see what changed and ensures the team is aware of any UI changes.
4. When to use:
   • Use snapshots selectively. Over-relying on them can lead to fragile tests, especially if the component changes frequently.
   • If your component has a lot of dynamic content (like dates or random values), it might not be a good candidate for snapshots unless you mock those dynamic values.

Publishing to NPM

NPM Configuration

• NPM Account is required
• This account needs to generate an access token.

Generating Access Tokens

1. In NPM, go to Profile -> Access Tokens
2. Click Generate New Token
   1. Select Classic Token
3. Enter a name (can be whatever you want), and select Automation
   1. An automation token will bypass two-factor authentication (2FA) when publishing. If you have 2FA enabled, you will not be prompted when using an automation token, making it suitable for CI/CD workflows.
4. Take the newly generated token, and add it as a CI/CD Variable named NPM_TOKEN within the simple-apps-components Gitlab repository.

Incrementing Versions Workflow (Do not do this, this is just as a record of how it's done)

We use a combination of package.json and Gitlab tags to increment versions, and doing so will automatically trigger a more robust pipeline that ultimately publishes the package to NPM.

When you're ready to publish a new version of the package to NPM, follow these steps:

1. Commit a new version value for "version" in package.json and push this change to the develop branch only

   1. Follow the SemVer scheme (Major.Minor.Patch)
   2. Write this down, you will need it later

2. Once the develop branch is ready to be merged to master (all tests pass, and "version" has been updated), create a merge request from develop to master

   1. Note: There is a pre-check stage that validates the version has been incremented when merging to master

3. Merge the branch. This will not trigger the publish stage yet

4. After the merge completes, you are ready to add a Gitlab Tag

5. From the simple-apps-components repo in Gitlab, navigate to Code -> Tags

   1. Create a new tag. This tag description should be in the following format: vX.X.X, with the numbers matching the version specified in package.json from step 1.
   2. 'Create From' should be master

6. Once this tag is assigned to the master branch, this will automatically trigger the publish pipeline with these stages:

   1. pre-check - validates that tags are only created on the master branch
   2. build - runs vite build and creates the /dist directory with TypeScript type definitions
   3. publish - consumes the NPM_TOKEN to publish the latest version to NPM

   Note: Tests only run automatically on the develop branch. Ensure all tests pass before merging to master.

Build Process

The build process uses Vite to bundle the component library and generate TypeScript declarations.

1. From inside the repository, run yarn build
2. This will:
   • Bundle the library into dist/simple-components.esm.js
   • Generate TypeScript type definitions in dist/types/
   • Create the bundled CSS in dist/style.css

Important note: do not commit the dist folder. It cannot be added to .gitignore because the dist folder needs to be published to NPM