@metrostar/comet-uswds

Comet

Comet is a React with TypeScript Component Library based on USWDS 3.0.

In order to utilize Comet within your app, you must first ensure USWDS is pre-configured in your app. Please review the following for details specific to USWDS prior proceeding: USWDS Documentation.

Getting Started with the Comet Starter App (recommended)

1. Clone the comet starter repo here: Comet Starter

2. Follow the steps for "Running the Project Locally"

Getting Started with a Custom App (pre-configured for USWDS)

1. Add Comet to your project:

# npm
npm i --save @metrostar/comet-uswds
# or yarn
yarn add @metrostar/comet-uswds

1. Add your first Comet component:

import { Alert } from '@metrostar/comet-uswds';

<Alert id="alert-1" type="info">
  This is the alert body
</Alert>;

Getting Started with a Custom App (NOT pre-configured for USWDS)

Note: the below setup assumes your project is setup for Vite and SCSS.

1. Add USWDS and Comet to your project:

# npm
npm i --save @uswds/uswds @metrostar/comet-uswds

# or yarn
yarn add @uswds/uswds @metrostar/comet-uswds

1. Add uswds directory to your src folder
2. Add base USWDS file (uswds.scss) to the uswds directory, with the following:

// Include a USWDS settings file (required)
@forward './uswds-settings.scss';

// Point to the USWDS source code (required)
@forward '~uswds/packages/uswds';

// Include your project's custom Sass (optional)
// @forward "project-custom.scss";

1. Add base USWDS settings file (uswds-settings.scss) to the uswds directory, with the following:

@use 'uswds-core' with (
  // General settings
  $theme-show-notifications: false,
  $theme-font-path: '~uswds/dist/fonts',
  $theme-image-path: '~uswds/dist/img'
);

1. Add uswds to the top of your your SASS entry point (styles.scss), with the following:

@forward 'uswds/uswds.scss';

1. Update your Vite config file (vite.config.ts) as needed with the following USWDS specific configurations:

import react from '@vitejs/plugin-react';
import autoprefixer from 'autoprefixer';
import path from 'path';
import { fileURLToPath } from 'url';
import { defineConfig } from 'vite';
import EnvironmentPlugin from 'vite-plugin-environment';
import eslint from 'vite-plugin-eslint';
import tsconfigPaths from 'vite-tsconfig-paths';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react(), tsconfigPaths(), eslint(), EnvironmentPlugin('all')],
  resolve: {
    alias: {
      '~uswds': path.resolve(__dirname, 'node_modules/@uswds/uswds'),
    },
  },
  css: {
    preprocessorOptions: {
      scss: {
        includePaths: ['node_modules/@uswds/uswds/packages'],
      },
    },
    postcss: {
      plugins: [autoprefixer],
    },
  },
});

1. Add your first Comet component:

import { Alert } from '@metrostar/comet-uswds';

<Alert id="alert-1" type="info">
  This is the alert body
</Alert>;

For any further troubleshooting, please refer to the comet starter app linked above.