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.