patrickcate / vue-uswds

A Vue 3 implementation of the USWDS.

Vue USWDS

A Vue 3 implementation of the USWDS. If you need Vue 2 support, check out the USWDS-Vue library.

Documentation

Installation

Note: You will need to install the USWDS CSS separately.

Vue USWDS can be installed either by including it with a simple script tag or using NPM and a build system.

Script Tag

The easiest way to include the library with a script tag is to use a CDN such as jsDelivr or unpkg. You can also load the library locally on your server.

When using with a script tag all components will be imported.

<script src="https://unpkg.com/vue@3"></script>
<script src="https://unpkg.com/vue-uswds"></script>

NPM (Node Package Manager)

npm install vue-uswds

// or

yarn install vue-uswds

Usage

When importing the library via NPM you can import all components or use the À La Carte method to import only specific components. The À La Carte method makes it easier to reduce the final bundle size of your application by only including components you are using.

All Components

import Vue from 'vue'
import VueUswds from 'vue-uswds'

const app = Vue.createApp({})

app.use(VueUswds, {
  // ...options
})

app.mount('#app')

À La Carte

// App.vue
import Vue from 'vue'
import VueUswds from 'vue-uswds/core' // Import only the core library.

const app = Vue.createApp({})

app.use(VueUswds, {
  // ...options
})

app.mount('#app')

// MyComponent.vue
<script>
import { UsaTag } from 'vue-uswds/components'

export default {
  components: { UsaTag },
}
</script>

<template>
  <UsaTag>My Custom Tag</UsaTag>
</template>

If there are components you wish to use anywhere in your app without first importing them, you can register them globally.

// App.vue
import Vue from 'vue'
import VueUswds from 'vue-uswds/core' // Import only the core library.
import { UsaTag } from 'vue-uswds/components'

const app = Vue.createApp({})

app.use(VueUswds, {
  // ...options
})

// Register any global components...
app.component('UsaTag', UsaTag)

app.mount('#app')

Recommended IDE Setup

• VSCode
• Volar

Contributing Guidelines

• Create an issue for any bugs or feature requests before doing any work.
• This project follows Conventional Commits naming conventions for all git commits.
  • The git commit format can be easily generated by running npm run commit which will use Comittizen to walk you through the formatting options of your commit.
• This project uses npm, not yarn or pnpm.
• Prettier and ESLint are run as pre-commit hooks to help maintain a consistent code style. They are also run with any PR's submitted.
• Cypress is used for all component tests.
  • All components must have tests.
  • Cypress can be run locally, but will also run with all PR's.
  • Tests must pass in order for PR's to be merged.
  • See the "Tests" section of this README for commands to run tests locally.
• Storybook is used for documentation.
  • All components must have a story.
  • You can preview Storybook locally by running npm run storybook.
• Vue's composition API is preferred over the options API.

Testing Github Actions Locally

Use act to test Github actions locally.

Note: Because the act docker containers do not have the XVFB dependency installed, you must use a custom docker container from Cypress by adding:

container:
  image: cypress/browsers:node14.17.0-chrome91-ff89

The specific container can be one of Cypress's docker images.

You may also need to temporarily adjust the node matrix versions to use the provided by the Cypress container.

Tests

Specific Cypress component tests:

node_modules/.bin/cypress run-ct  --spec="src/components/UsaDatePickerCalendar/UsaDatePickerCalendar.test.js" --headed --no-exit

All Cypress component tests headless:

npm run test:component

Headed Cypress interactive component tests:

npm run cypress:open-ct