### Verify Git Branch Installation in yarn.lock Source: https://github.com/trussworks/react-uswds/blob/main/docs/contributing.md After installing from a Git branch, you can verify the installation by checking your `yarn.lock` file. The `resolved` field should point to the Git repository and commit SHA. ```text "@trussworks/react-uswds@https://github.com/trussworks/react-uswds": version "1.13.2" resolved "https://github.com/trussworks/react-uswds#92ea5f07f7212370165423ec09ed35eec3aa7e58" ``` -------------------------------- ### Install ReactUSWDS from Git Branch Source: https://github.com/trussworks/react-uswds/blob/main/docs/contributing.md Alternative method to install a specific, unreleased version of ReactUSWDS directly from a Git branch. Update your `package.json` with the Git URL and branch name, then run `yarn install`. ```json "@trussworks/react-uswds": "https://github.com/trussworks/react-uswds#name-of-branch", ``` -------------------------------- ### Install Project Dependencies with Yarn Source: https://github.com/trussworks/react-uswds/blob/main/docs/codespace_pr_reviews.md Installs all necessary project dependencies using the Yarn package manager. This step is essential to ensure the project environment is correctly set up before running development or build tasks. It downloads and links packages specified in the project's configuration. ```shell yarn install ``` -------------------------------- ### Run react-uswds Storybook Locally Source: https://github.com/trussworks/react-uswds/blob/main/docs/design-pr-reviews.md Command to start the Storybook development server for the react-uswds project. This hosts the project's UI components for local viewing and testing. ```bash yarn storybook ``` -------------------------------- ### Install @trussworks/react-uswds Source: https://github.com/trussworks/react-uswds/blob/main/README.md Instructions for adding the @trussworks/react-uswds package to your project using npm or yarn. ```bash yarn add @trussworks\/react-uswds ``` ```bash npm i @trussworks\/react-uswds ``` -------------------------------- ### Link ReactUSWDS in Application Source: https://github.com/trussworks/react-uswds/blob/main/docs/contributing.md Command to link the locally developed ReactUSWDS package into your application's `node_modules`. This replaces the installed version with your local development version. ```bash cd /path/to/your/application ➜ yarn link @trussworks/react-uswds yarn link v1.22.4 success Using linked package for "@trussworks/react-uswds". ``` -------------------------------- ### Run Storybook Development Server with Yarn Source: https://github.com/trussworks/react-uswds/blob/main/docs/codespace_pr_reviews.md Starts the Storybook development server to preview components interactively. This command builds and serves the Storybook UI, typically accessible on port 9009. It allows developers to view and test components in isolation. ```shell yarn storybook ``` -------------------------------- ### Development Commands Source: https://github.com/trussworks/react-uswds/blob/main/docs/contributing.md Commonly used Yarn commands for developing and testing the react-uswds project. These commands facilitate starting Storybook, running tests, and building the project. ```shell yarn storybook # Starts Storybook server and watches for changed files # This will most likely be what you use for active development of components ``` ```shell yarn test # Starts test runner # yarn test:watch is also available # Use yarn test:coverage to generate a coverage report ``` ```shell yarn build # Builds files from /src and outputs to /lib using webpack and UMD library target # yarn build:watch is also available ``` -------------------------------- ### Update Project README Source: https://github.com/trussworks/react-uswds/blob/main/docs/for_trussels.md Instructions for maintainers to update the main project README file, specifically regarding the 'Active Maintainers' list. ```shell Add yourself to main project README "Active Maintainers" list. ``` ```shell Open a new PR that removes yourself from the Active Maintainers list in the README. ``` -------------------------------- ### Draft PR for In-Progress Work Source: https://github.com/trussworks/react-uswds/blob/main/docs/for_trussels.md Guidance on creating a draft pull request to document and hand off in-progress work. This includes annotating remaining tasks, TODOs, and strategy. ```shell Open a draft PR for your branch, and use that to annotate any remaining work, TODOs, open questions, etc. as well as the overarching strategy you had in mind. ``` -------------------------------- ### Manage CODEOWNERS File Source: https://github.com/trussworks/react-uswds/blob/main/docs/for_trussels.md Guidance on adding or removing oneself from the CODEOWNERS file. This file automatically requests reviews from specified users for pull requests affecting certain files. ```shell Add yourself to CODEOWNERS if you'd like to automatically be requested to review PRs. ``` ```shell Remove yourself from CODEOWNERS so you don't get PR requests that you won't have time to review. ``` -------------------------------- ### Unlink ReactUSWDS Package Source: https://github.com/trussworks/react-uswds/blob/main/docs/contributing.md Command to remove the symlink and revert your application to using the version of ReactUSWDS installed from a registry or Git. Requires a subsequent `yarn install --force`. ```bash cd /path/to/your/application ➜ yarn unlink @trussworks/react-uswds yarn unlink v1.22.4 success Removed linked package "@trussworks/react-uswds". info You will need to run `yarn install --force` to re-install the package that was linked. ➜ yarn install --force ``` -------------------------------- ### Request npm Organization Access Source: https://github.com/trussworks/react-uswds/blob/main/docs/for_trussels.md Instructions for maintainers to request access to the npm organization. This is a necessary step for publishing new releases of the package. ```shell Ping in #react-uswds to request access to the npm org ``` -------------------------------- ### Add Contributor to README Source: https://github.com/trussworks/react-uswds/blob/main/docs/for_trussels.md Command to add a contributor to the project's README file. This typically involves using a script provided by the project to manage the contributors list. ```shell yarn contributors:add [your github username] code ``` -------------------------------- ### Request Happo Account Admin Privileges Source: https://github.com/trussworks/react-uswds/blob/main/docs/for_trussels.md Instructions for maintainers to request admin privileges for the Happo account. Happo is likely used for visual regression testing or component previews. ```shell Ping in #react-uswds to request admin privileges to the Happo Account ``` -------------------------------- ### Use USWDS SCSS Mixin Source: https://github.com/trussworks/react-uswds/blob/main/docs/styles_and_assets.md After setting up SCSS imports, you can utilize USWDS mixins and functions in your project's SCSS files. This example shows applying a background color utility. ```scss // your-project/myProject.scss .myProjectElement { @include u-bg('info-lighter'); } ``` -------------------------------- ### Configure npm for GitHub Packages Pre-releases Source: https://github.com/trussworks/react-uswds/blob/main/docs/prerelease.md Set up your `.npmrc` file to use GitHub Packages as a registry for pre-release packages. This requires specifying the authentication token and the registry URL for the `@trussworks` scope. ```npmrc //npm.pkg.github.com/:_authToken=YOUR_TOKEN_GOES_HERE @trussworks:registry=https://npm.pkg.github.com ``` -------------------------------- ### Manual Publishing Steps Source: https://github.com/trussworks/react-uswds/blob/main/docs/releasing.md Steps to manually publish a new package version to npm when the Continuous Integration (CI) system is down. This involves fetching tags, checking out the release tag, rebuilding the application, and publishing. ```shell git fetch --all --tags ``` ```shell git checkout 1.1.0 ``` ```shell rm -rf node_modules && yarn && yarn build ``` ```shell npm publish ``` -------------------------------- ### Use Pre-release Version in package.json Source: https://github.com/trussworks/react-uswds/blob/main/docs/prerelease.md Specify the pre-release version of the `@trussworks/react-uswds` package in your `package.json` file. Use 'next' to track the latest pre-release build from the main branch. ```json { "dependencies": { "@trussworks/react-uswds": "next" } } ``` -------------------------------- ### Import ReactUSWDS Components Source: https://github.com/trussworks/react-uswds/blob/main/README.md Demonstrates how to import components from the library using ES6 syntax. ```javascript import { Alert } from '@trussworks\/react-uswds' ``` -------------------------------- ### Link ReactUSWDS Package Locally Source: https://github.com/trussworks/react-uswds/blob/main/docs/contributing.md Command to register the local ReactUSWDS package for linking in other projects. This makes the package available to be linked into other applications. ```bash cd /path/to/react-uswds ➜ yarn link yarn link v1.22.4 success Registered "@trussworks/react-uswds". info You can now run `yarn link "@trussworks/react-uswds"` in the projects where you want to use this package and it will be used instead. ``` -------------------------------- ### Linting and Formatting Commands Source: https://github.com/trussworks/react-uswds/blob/main/docs/contributing.md Commands to check and apply code formatting and linting rules using Yarn. These ensure code consistency and quality across the project. ```Shell yarn format:check yarn format:fix yarn lint ``` -------------------------------- ### Publish Package to npm Source: https://github.com/trussworks/react-uswds/blob/main/docs/releasing.md Command to publish the new package version to the npm registry. Requires the path to the tarball artifact and may prompt for MFA. Ensure you are logged in via `npm login`. ```sh npm publish ``` -------------------------------- ### Download Release Artifact Source: https://github.com/trussworks/react-uswds/blob/main/docs/releasing.md Instructions for downloading the release artifact (.tgz file) from a GitHub Actions workflow run. This is typically done after a release PR is merged. ```sh unzip artifact.zip ``` -------------------------------- ### Download Release Artifact using GitHub CLI Source: https://github.com/trussworks/react-uswds/blob/main/docs/releasing.md Alternative method to download the release artifact using the GitHub CLI. Requires the run ID of the relevant GitHub Actions workflow. ```sh gh run download ``` -------------------------------- ### Add Contributor using Yarn CLI Source: https://github.com/trussworks/react-uswds/blob/main/docs/contributing.md Demonstrates how to use the project's CLI script to add contributors and specify their contribution types. This command interacts with the All Contributors bot to update project acknowledgments. ```Shell yarn contributors:add github-person code,doc ``` -------------------------------- ### Include Compiled CSS Source: https://github.com/trussworks/react-uswds/blob/main/README.md Shows how to import the compiled CSS from the library into your project's stylesheets. ```css @import '~@trussworks\/react-uswds\/lib\/index.css'; ``` -------------------------------- ### Storybook Imports Source: https://github.com/trussworks/react-uswds/blob/main/src/stories/welcome.mdx Imports core components from the Storybook blocks addon, used for defining story metadata and structure. ```javascript import { Meta, Story, Canvas } from '@storybook/blocks'; ``` -------------------------------- ### NextJS Webpack Configuration for Linked Packages Source: https://github.com/trussworks/react-uswds/blob/main/docs/contributing.md For NextJS applications, you might need to adjust the Webpack configuration to correctly alias `react` and handle server-side rendering externals when using linked packages. ```javascript webpack: (config, options) => { if (options.isServer) { config.externals = ['react', ...config.externals] } config.resolve.alias['react'] = path.resolve(__dirname, '.', 'node_modules', 'react') return config } ``` -------------------------------- ### Configure yarn for GitHub Packages Pre-releases Source: https://github.com/trussworks/react-uswds/blob/main/docs/prerelease.md Configure your `.yarnrc` file to use GitHub Packages as a registry for pre-release packages. This involves setting the registry URL for the `@trussworks` scope. ```yarnrc "@trussworks:registry" "https://npm.pkg.github.com" ``` -------------------------------- ### Link React and React-DOM for Hook Errors Source: https://github.com/trussworks/react-uswds/blob/main/docs/contributing.md If encountering invalid hook call errors, you may need to link the `react` and `react-dom` packages similarly to the main library. This ensures consistent versions across your linked packages. ```bash ➜ cd /path/to/react-uswds ➜ yarn link ➜ yarn install ➜ cd node_modules/react ➜ yarn link ➜ cd ../../node_modules/react-dom ➜ yarn link ➜ cd /path/to/your/application ➜ yarn link @trussworks/react-uswds ➜ yarn link react ➜ yarn link react-dom ``` -------------------------------- ### Storybook Meta Configuration Source: https://github.com/trussworks/react-uswds/blob/main/src/stories/welcome.mdx Configures the metadata for a Storybook story, specifically setting the title that appears in the Storybook sidebar. ```jsx ``` -------------------------------- ### Import USWDS SCSS Source: https://github.com/trussworks/react-uswds/blob/main/docs/styles_and_assets.md To use USWDS SCSS, define required SCSS variables in a theme file, such as '_uswds-theme.scss'. Then, import the theme and USWDS core styles in your main SCSS file. ```scss // your-project/_uswds-theme.scss @use 'uswds-core' with ( $theme-image-path: '@uswds/uswds/img', $theme-font-path: '@uswds/uswds/fonts', $theme-hero-image: '@uswds/uswds/img/hero.jpg' ); ``` ```scss // your-project/index.scss // Custom theme settings/USWDS overrides go here @forward 'uswds-theme'; @forward 'uswds'; @forward 'uswds-custom-styles'; ``` -------------------------------- ### Import USWDS CSS Source: https://github.com/trussworks/react-uswds/blob/main/docs/styles_and_assets.md Import USWDS CSS files into your React application. If you do not have 'uswds' as an existing dependency, import both 'uswds.css' and 'index.css'. If 'uswds' is already a dependency, only 'index.css' is typically needed. ```javascript import '@trussworks/react-uswds/lib/uswds.css' import '@trussworks/react-uswds/lib/index.css' ``` ```javascript import '@trussworks/react-uswds/lib/index.css' ``` -------------------------------- ### Configure USWDS SCSS Variables Source: https://github.com/trussworks/react-uswds/blob/main/docs/styles_and_assets.md Customize USWDS SCSS variables by defining them in a settings file, ensuring the order matches the original USWDS theme styles. This allows for extensive theming, including typography and spacing. ```scss // your-project/_uswds-theme.scss @use 'uswds-core' with ( $theme-image-path: '@uswds/uswds/img', $theme-respect-user-font-size: false, $theme-root-font-size: 14px, $theme-font-path: '@uswds/uswds/fonts', $theme-font-type-sans: 'public-sans', $theme-style-body-element: true, $theme-grid-container-max-width: 'desktop-lg', $theme-hero-image: '@uswds/uswds/img/hero.jpg' ); ``` -------------------------------- ### Pull Request Commit Message Format Source: https://github.com/trussworks/react-uswds/blob/main/docs/contributing.md Guidelines for formatting commit messages when submitting pull requests to ensure consistency and clarity. Follows a conventional commit structure. ```APIDOC Commit Message Format: [optional scope]: [optional body] [optional footer] - **type**: Describes the kind of change (e.g., feat, fix, chore, docs, style, refactor, test, perf, build, ci, revert). - **scope**: An optional section specifying the part of the codebase affected (e.g., components/button, utils/api). - **description**: A concise summary of the change, starting with a lowercase letter and not ending with a period. - **body**: An optional, more detailed explanation of the change, providing context and rationale. - **footer**: An optional section for referencing issues (e.g., Closes #123) or noting breaking changes. ``` -------------------------------- ### Conventional Commit Message Structure Source: https://github.com/trussworks/react-uswds/blob/main/docs/contributing.md Defines the standard format for commit messages, crucial for automated changelog generation and versioning. It includes a type, optional scope, subject, an optional body, and an optional footer for linking issues or indicating breaking changes. ```Conventional Commits (scope):