simple-apps-components v1.0.66

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     # Rollup entry point

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 2 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

Example of index.js

export { default as SimpleButton } from './components/SimpleButton.vue';
export { default as SimpleCard } from './components/SimpleCard.vue';

5. Finally, send merge request for review

Testing

Jest 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:

/**
 * @jest-environment jsdom
 */

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, Jest 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, Jest 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: jest path/to/your/testfile.spec.js --updateSnapshot
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, Jest 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
3. Merge the branch. This will not trigger the publish stage still
4. After the pipeline for the merge finishes (just another testing stage), then 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 verbose pipeline with 3 stages:
   1. build - runs rollup and creates the /dist directory
   2. test - same stage that runs on the develop branch. Tests all components and files
   3. publish - consumes the NPM_TOKEN to publish the latest version to NPM

Build Analyzing

It's necessary to sometimes analyze the size of the bundle being generated by the package. A plugin has been added to rollup to run a visualizer on the bundle after build only when ran manually (excludes the pipeline)

1. From inside the repository, run yarn build
2. After the build is run, a browser window will open with a Treemap of the bundled package

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