AIS Components

Developing AIS Components

We welcome contributions from all parts of AIS and the OneIT community -- including feedback, bug reports, documentation, and merge requests. The information below will help you understand the project structure, build the project, and start making changes.

AIS Components is hosted in a private GitLab repository (login required). Questions and discussions on library usage should be directed to the #tool-ais-components slack channel. Collaborators may ask to join the #collab-ais-components channel.

Project Structure

Once you have the project checked out locally, take a tour of the file structure below to get a lay of the land.

  • package.json - Project definition including build steps and dependencies.
  • index.html - Components and related resources are exposed here.
  • docs
    • /.vitepress/config.json - Defines the structure of the docs site.
    • /**/*.md - Documentation pages are defined in Markdown files.
  • src
    • /components - Components root
    • /composables - Composables root
    • /css - CSS root

Component Structures

The library's components, rooted under /src/components, have their own directory with a common structure. The structure is intended to group all the code for defining, testing, and illustrating a component. A component definition may contain Vue, Javascript, and Typescript files. The src/components/button directory is shown below as an archetype.

  • /button
    • /examples - Vue files demonstrating common usage for the docs site.
    • /tests - Vitest files exercising the component.
      • ais-button.test.js
      • base-button.test.js
    • AisButton.vue
    • BaseButton.vue
    • baseProps.js

Build

We use Yarn v1 to build the library, and the build stages are defined in package.json. The build commands below are the primary builds we use when developing AIS Components.

docs:dev

yarn docs:dev runs the docs site in development mode on port 4000. This gives you an environment where you can develop and exercise a component with live-reload. Typically, you will work on a component and review changes in an example component on a documentation page.

test

yarn test runs the Vitest unit tests in interactive mode. The test configuration will automatically execute all files with the form *.test.js, which we include in a components /tests directory. Relevant tests will automatically re-run as component code changes. You can run a single test with yarn test ais-button.test.js.

build

yarn build builds the library for production. This build stage is invoked in out CI/CD pipeline as defined in .gitlab-ci. You may need to trigger this manually if you are publishing a test version of the library.

Publish

Ask in #collab-ais-components if you need to publish test versions of the library, and we can help you get started. The quick process (if all is configured correctly) is as follows:

  • Make sure you have a unique version specified in package.json. We usually qualify the current version with an issue number and sequence. For example, if we're building on 0.3.30 working in issue #555 we would define the test version as 0.3.30-555-1.
  • yarn build
  • npm publish

Test packages are published to uiowa-ais-public/packages.