Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# Agent instructions (PatternFly React Seed)

This file helps humans and coding agents work safely in this repository. It summarizes how the app is built, how to validate changes, and where code lives.

## What this project is

Official [PatternFly React seed](https://github.com/patternfly/patternfly-react-seed): a small React + TypeScript app with PatternFly layout, React Router, Webpack, and Vitest. It is a reference for wiring PatternFly into a real app, not a component library.

## Stack

- **React** 18, **TypeScript** (strict), **PatternFly** v6 (`@patternfly/react-core`, `@patternfly/react-icons`, `@patternfly/react-styles`)
- **Bundler**: Webpack (`webpack.*.js`); dev server: `webpack-dev-server`
- **Tests**: **Vitest** + Testing Library (`vitest.config.ts`, `src/test/setup.ts`) — not Jest
- **Lint**: ESLint on `./src/` (`.tsx`, `.js`); **unused imports and variables are errors**

## Commands to run before you consider work done

From the repository root, after `npm install`:

| Command | Purpose |
|--------|---------|
| `npm run type-check` | TypeScript (`tsc --noEmit`) |
| `npm run lint` | ESLint on `src/` |
| `npm test` | Vitest unit tests |
| `npm run test:coverage` | Vitest with coverage (requires devDependency `@vitest/coverage-v8`) |
| `npm run ci-checks` | Same as type-check + lint + `test:coverage` (run this before merging when possible) |

Local development:

| Command | Purpose |
|--------|---------|
| `npm run start:dev` | Webpack dev server |
| `npm run build` | Production build into `dist/` |

## Repository layout

- `src/app/` — Application shell: routes, layout, feature pages (Dashboard, Settings, Support, NotFound)
- `src/app/AppLayout/` — Chrome (header/sidebar)
- `src/component/` — Shared or prototype components
- `src/index.tsx` — Entry; dev-only `react-axe` wiring when not in production
- `webpack.common.js` — Shared Webpack config (aliases, loaders)
- `vitest.config.ts` — Test runner and `@app` alias for tests

## Path aliases

- `@app/*` → `src/app/*` (Webpack and Vitest)
- `@assets/*` → PatternFly packaged assets under `node_modules/@patternfly/react-core/dist/styles/assets/*`

Use these for imports instead of long relative paths where the codebase already does.

## PatternFly and UI conventions

- Global styles: import `@patternfly/react-core/dist/styles/base.css` from the app root (see `src/app/index.tsx`).
- Prefer PatternFly React components for structure and layout (`Page`, `PageSection`, navigation patterns) before ad hoc markup or utility-only layouts.
- Match existing file style: quote style, import order (ESLint `sort-imports` is enabled with `ignoreDeclarationSort`).

## Testing

- Tests live next to features (e.g. `src/app/app.test.tsx`).
- Vitest uses `jsdom` and `./src/test/setup.ts` for globals/setup.

## Things that commonly break CI

- **Unused imports or variables** in `src/` — fix or remove them; ESLint treats them as errors.
- **Omitting `npm run lint` or `npm run type-check`** after edits — run at least those before opening a PR.
- **`npm run ci-checks` fails on coverage** — ensure `@vitest/coverage-v8` is installed (`npm install`) and matches the major Vitest version in `package.json`.

## Optional: PatternFly MCP

For up-to-date PatternFly component APIs and docs, agents can use the [PatternFly MCP server](https://www.npmjs.com/package/@patternfly/patternfly-mcp) if the user’s environment has it configured.

## When unsure

- Prefer patterns already used under `src/app/`.
- Read `README.md` for asset loading (`@app`, `@assets`, SVG/bgimages) and script reference.
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,16 +39,18 @@ npm run format
# Launch a tool to inspect the bundle size
npm run bundle-profile:analyze

# Start the express server (run a production build first)
# Serve the production build with sirv (run npm run build first)
npm run start
```

## Configurations
* [TypeScript Config](./tsconfig.json)
* [Webpack Config](./webpack.common.js)
* [Jest Config](./jest.config.js)
* [Vitest Config](./vitest.config.ts)
* [Editor Config](./.editorconfig)

For coding agents and automation, see [AGENTS.md](./AGENTS.md) (validation commands, layout, and conventions).

## Raster image support

To use an image asset that's shipped with PatternFly core, you'll prefix the paths with "@assets". `@assets` is an alias for the PatternFly assets directory in node_modules.
Expand Down Expand Up @@ -88,7 +90,7 @@ When importing CSS from a third-party package for the first time, you may encoun
* For accessibility compliance, we use [react-axe](https://github.com/dequelabs/react-axe)
* To keep our bundle size in check, we use [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer)
* To keep our code formatting in check, we use [prettier](https://github.com/prettier/prettier)
* To keep our code logic and test coverage in check, we use [jest](https://github.com/facebook/jest)
* To keep our code logic and test coverage in check, we use [Vitest](https://vitest.dev/)
* To ensure code styles remain consistent, we use [eslint](https://eslint.org/)

## Multi environment configuration
Expand Down
Loading
Loading