Getting Started

Getting started with USWDS + Tailwind is fast and easy. By copying and pasting the following snippets, you'll be up and running in minutes.

Setup

Initialize your project

mkdir my-project && cd my-project
npm init -y

Install dependencies

This project requires installing a few dependencies to get started:

USWDS + Tailwind

npm i @uswds-tailwind/compat @uswds-tailwind/theme

Tailwind and plugins

npm i tailwindcss @tailwindcss/vite @iconify-json/fa-solid @iconify-json/fa6-brands @iconify-json/material-symbols

Install fonts

npm i @fontsource-variable/open-sans @fontsource-variable/public-sans @fontsource-variable/roboto-mono @fontsource-variable/source-sans-3 @fontsource-variable/merriweather

Project structure

Now that we’ve installed our necessary dependencies, let’s build out our project structure and finish setting up our various configurations.

mkdir {src,src/assets,src/assets/js,src/assets/css}
touch src/index.html src/assets/js/main.js src/assets/css/styles.css .gitignore

Your project structure should look like this:

my-project/
├── node_modules/
├── src/
│   ├── assets/
│   │   ├── js/
|   |   │   └── main.js
│   │   └── css/
|   |       └── styles.css
|   └── index.html
├── package-lock.json
└── package.json

Configure project

CSS

Then, import your fonts, Tailwind, and the @uswds-tailwind/theme directives into your src/assets/css/styles.css file.

/* Only import the fonts you need! */
@import "@fontsource-variable/open-sans";
@import "@fontsource-variable/public-sans";
@import "@fontsource-variable/roboto-mono";
@import "@fontsource-variable/source-sans-3";
@import "@fontsource-variable/merriweather";

@import "tailwindcss";
@import "@uswds-tailwind/theme";

JavaScript

Now, update your src/assets/js/main.js file to initialize your JavaScript components.

More information about component specific plugins can be found on the JavaScript page.

// Option 1: Auto-initialize all components
import '@uswds-tailwind/compat/auto'

// Option 2: Manual initialization with only the components you need
import { modalInit, accordionInit } from '@uswds-tailwind/compat'
document.addEventListener('DOMContentLoaded', () => {
  modalInit()
  accordionInit()
})

Finally, update your src/index.html with the following:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>USWDS + Tailwind</title>
    <link rel="stylesheet" href="../build/css/styles.css" />
  </head>
  <body class="font-source-sans">
    <div class="py-4 px-3 mx-auto max-w-screen-desktop">
      <h1 class="text-4xl font-bold max-w-prose mb-4">
        Welcome to USWDS + Tailwind!
      </h1>
      <button
        type="button"
        class="rounded-sm font-bold leading-none cursor-pointer text-white px-5 py-3 bg-blue-60v hover:bg-blue-warm-70v active:bg-blue-warm-80v focus:outline-4 focus:outline-offset-4 focus:outline-blue-40v"
      >
        Default
      </button>
    </div>

    <script type="module" src="../assets/js/main.js"></script>
  </body>
</html>

.gitignore

Before we push any code to our repository, we’ll want to add a .gitignore file. This way, we dont push unnecessary or redundant code to our remote repository.

Our .gitignore should include the following:

node_modules

.parcel-cache

build

If you’re manually compiling your CSS and JavaScript assets locally before a deployment, don’t add the build directory to your .gitignore.

Complete!
Awesome, now everything is set up! You can run npm run dev and open the index.html file to see your project in action!
If you’re using any of the interactive components that require JavaScript, head to the JavaScript page to see how to implement the various plugins.