Getting Started

Setup

You’ll need Node.js and npm installed, plus some familiarity with the terminal.

Create a project folder

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

Install dependencies

Install Vite, Tailwind CSS, and Tailwind’s Vite plugin as development dependencies. Then install the USWDS + Tailwind packages.

npm install -D vite tailwindcss @tailwindcss/vite
npm install @uswds-tailwind/compat@latest @uswds-tailwind/theme@latest

Now that the dependencies are installed, we can create the project files.

Project structure

Create the HTML, CSS, and JavaScript files. Keep index.html in the project root, where Vite looks for it by default. Run this from my-project, or create the files manually.

mkdir src
touch index.html src/main.js src/styles.css vite.config.js .gitignore

Your project should look like this:

my-project/
├── src/
│   ├── main.js
│   └── styles.css
├── .gitignore
├── index.html
├── package-lock.json
├── package.json
└── vite.config.js

Configure project

Vite

Vite will serve index.html and build the site into dist by default. In vite.config.js, we only need to enable Tailwind CSS:

import tailwindcss from '@tailwindcss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [tailwindcss()],
})

Add scripts to package.json to run the development server and build the site:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}

CSS

Import Tailwind CSS and the USWDS theme in src/styles.css:

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

JavaScript

Then import the stylesheet and component JavaScript in src/main.js:

import './styles.css'
import '@uswds-tailwind/compat/auto'

The JavaScript import initializes matching interactive components when the page loads. See the component examples for their HTML markup.

HTML

Finally, fill in index.html. The module script loads src/main.js, which imports the stylesheet and component JavaScript.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>USWDS + Tailwind</title>
    <script type="module" src="./src/main.js"></script>
  </head>
  <body class="font-source-sans">
    <main class="mx-auto max-w-prose p-6">
      <h1 class="mb-6 text-3xl font-bold">Hello, USWDS + Tailwind!</h1>
      <button type="button" class="rounded-sm bg-blue-60v px-5 py-3 font-bold text-white hover:bg-blue-warm-70v focus:outline-4 focus:outline-blue-40v">
        Button
      </button>
    </main>
  </body>
</html>

.gitignore

Add generated files to .gitignore:

node_modules/
dist/

Complete!

The button lets you see that the styles are loading. Run npm run dev from my-project and open the local URL Vite prints.

When you’re ready to deploy, run npm run build and publish the generated dist directory.