Setup React Web

This documentation was generated with the assistance of AI. Please report any inaccuracies.

Scaffold a React + TypeScript web application with Vite, then layer on this catalog’s standard test/coverage/lint/format/e2e toolchain — Vitest, Testing Library, ESLint or Oxlint, Prettier, Stylelint, Playwright, an optional Storybook setup, and sonar-project.properties when Sonar is enabled. It also makes the scaffold ready for the catalog’s UI contract (see Building user interfaces): a Playwright component-testing project with a component gallery, axe accessibility checks, and a .ui-quality.yml.

Purpose

iru-setup-react-web bootstraps a new React web app from npm create vite@latest <name> — --template react-ts, then wires in the house toolchain this catalog expects every TypeScript project to carry: Vitest (jsdom, v8 coverage with lcov) plus @testing-library/react for unit tests, ESLint 10 flat config with eslint-plugin-react-hooks (or the Vite template’s own Oxlint, kept by choice), Prettier, Stylelint 17 for CSS, Playwright for an end-to-end smoke test under e2e/, an optional Storybook setup, and — when Sonar is enabled — sonar-project.properties. There is no publish/distribution question for this skill, since a web app isn’t published to a package registry or an app store. Every step was proven against the actual current tooling (Vite 8, ESLint 10, Vitest 5, Playwright 1.63, Stylelint 17, Storybook 10) in a throwaway scaffold, so the gotchas called out along the way are observed behavior, not speculation.

A dedicated UI-contract step (Step 6b, with reference/ui-screenshots.ts) adds Playwright’s built-in mount() component testing driven by a Vite-served gallery (playwright/gallery/), @axe-core/playwright, a shared e2e/support/ui-screenshots.ts helper, and a sample screen spec that captures .ui-screenshots/screen/App/ across left-to-right/right-to-left x light/dark with an accessibility check in every cell. It also switches the template’s CSS to logical properties (so right-to-left captures mirror) and fixes the template’s low-contrast accent colour, then writes .ui-quality.yml at the repository root with the chosen accessibility level.

Purpose group

TypeScript/Node Bootstrap

Plugin

Shipped by the iru-typescript plugin of the ai-catalog marketplace (install with /plugin install iru-typescript@ai-catalog; see Plugins).

Invocation

/iru-setup-react-web

Inputs

Argument Required Description Default

args

No

Pre-resolved parameters passed by an orchestrating skill (e.g. Setup TypeScript Repository) as newline-separated key: value lines — see the keys below. Every field found here is resolved and Step 2 skips asking about it; if args is absent or unrecognized, every field is asked interactively.

None

app-name

No

package.json name — only asked when scaffolding into a subdirectory; otherwise defaults to the repository root directory’s own basename.

Root directory basename

description

Yes (unless supplied via args)

One-line project description written into package.json.

None

license

Yes (unless supplied via args)

Resolved via AskUserQuestion: Apache License 2.0, MIT License, No license, or Other (display name and URL asked directly).

None — user must choose

developer-name / developer-email / organization-url

Yes (unless supplied via args)

Populates package.json’s `author field.

None

open-source

No

Whether the repository is open source (yes/no) — informs the sonar recommendation together with visibility.

Asked with AskUserQuestion

sonar

No

cloud, self-hosted, or none, plus sonar-organization/sonar-project-key/sonar-host-url when cloud/self-hosted. Controls whether sonar-project.properties is written in Step 8. cloud is recommended only for a repository that is both public and open source (SonarCloud is free only for public open-source projects, per its current pricing); otherwise none is recommended, with self-hosted SonarQube as the alternative.

cloud recommended if public and open source, otherwise none recommended

keep-oxlint

No

yes keeps the Vite template’s Oxlint script alongside the new ESLint config; no replaces Oxlint with ESLint entirely.

Asked once with AskUserQuestion (recommended: no)

storybook

No

Whether to add an optional Storybook setup (yes/no) — reshapes vitest.config.ts into a multi-project config when enabled.

no

visibility

No

public, private, or internal — the GitHub repository’s visibility, used only to key the sonar recommendation. internal counts as private. If open-source: yes but visibility is private/internal, the skill warns and asks which is right.

Resolved only when the sonar question is asked: gh repo view --json visibility -q .visibility, else asked (Public recommended when open source)

ci

No

yes/no — whether the run invoking this skill generates GitHub Actions workflows at all; consulted only by the sonar question. With ci: no, none is recommended for Sonar since no CI would send reports (sonar-project.properties is still written if the user picks cloud/self-hosted, and the report says so).

yes implied

accessibility

No

enforce, report, off, or none — whether accessibility and assistive-technology support is wanted and the automated level of the UI tests, written to .ui-quality.yml in Step 6b. enforce makes axe violations fail the tests; report lists them without failing; off does not run them; none opts out entirely (no axe-core or eslint-plugin-jsx-a11y, no accessibility attributes in the templates).

Asked with AskUserQuestion (recommended: enforce; enforce when run via args without it)

on-existing

No

ask/keep/update/replace — how Step 1 treats each pre-existing artifact. keep/update/replace is applied to every one without asking (the warning is still printed); meant for scripted runs.

ask

mode

No

new or existing. existing marks the run as an update of an established repository, but never means "update silently" — Step 1 still warns and asks per pre-existing artifact unless on-existing says otherwise.

Derived from whether package.json exists (absent ⇒ new, present ⇒ existing)

Outputs

  • A Vite + React + TypeScript app scaffolded at the repository root or a subdirectory, including package.json, vite.config.ts, tsconfig.json (project references), src/, and public/.

  • vitest.config.ts, src/test/setup.ts, and src/App.test.tsx for unit testing.

  • eslint.config.js (or Oxlint left in place, per keep-oxlint), .prettierrc, .prettierignore, .stylelintrc.json.

  • playwright.config.ts and e2e/smoke.spec.ts for end-to-end testing, with the Chromium browser binary installed locally.

  • .ui-quality.yml at the repository root (accessibility, directions: [ltr, rtl], themes: [light, dark]).

  • The UI-contract test scaffold: e2e/support/ui-screenshots.ts (from reference/ui-screenshots.ts), playwright/gallery/index.html + main.tsx, src/App.story.tsx, e2e/components/App.spec.ts, a components Playwright project, the @axe-core/playwright dev dependency, and logical-property CSS fixes; running the specs produces the .ui-screenshots/ captures (kept out of version control).

  • .storybook/ and its scripts, only if storybook: yes.

  • sonar-project.properties at the repository root, only if sonar resolved to cloud or self-hosted.

  • tsconfig.e2e.json and an updated tsconfig.json reference list, so tsc -b type-checks e2e/ too.

  • A report that opens by repeating the announced mode (scaffolded from scratch or updated an existing setup), lists per owned artifact the action taken (created / updated / replaced / kept as is / removed) and each mismatch left by a kept artifact (e.g. a sonar-project.properties left after sonar: none, a Playwright config still listing Firefox/WebKit), every verification command run (typecheck, lint, format, test, coverage, build, e2e) and its result, the visibility used for Sonar and where it came from, plus explicit warnings to review generated files, wire SONAR_TOKEN in CI if Sonar was enabled, and provision Playwright browsers in CI.

Execution flow

flowchart TD A[Start /iru-setup-react-web] --> B{"Step 0: args supplied?"} B -- yes --> C[Parse key: value pairs from args] B -- no --> D[Treat every field as unset] C --> E["Step 1: Survey every owned artifact\n(package.json, Vitest/Jest, linter, Prettier,\nStylelint, Playwright, UI-contract files, Storybook, Sonar)"] D --> E E -- "nothing exists" --> F[Announce: scaffolding from scratch] E -- "anything exists or mode: existing" --> G[Announce: updating an existing setup; warn] G --> H{"on-existing keep/update/replace?"} H -- yes --> I[Apply it to every existing artifact] H -- no --> J["AskUserQuestion per artifact:\nUpdate / Keep as is / Replace / Stop"] J -- Stop --> K[Report untouched; end] J -- other --> L I --> L["Placement check (only if create-vite will run):\nempty root or subdirectory"] F --> L L --> M["Step 2: Collect app-name, description, developer info,\nlicense, open-source, visibility, sonar, keep-oxlint, storybook, accessibility"] M --> N["Step 3: npm create vite@latest --template react-ts;\nnpm install (only if no package.json or Replace)"] N --> O["Step 4: Add Vitest + Testing Library + jsdom;\nwrite App.test.tsx (skipped if Jest is kept)"] O --> P["Step 5: Add ESLint or keep Oxlint;\nPrettier; Stylelint (auto-fix CSS)"] P --> Q["Step 6: Add Playwright e2e;\nrename tests/ to e2e/; install Chromium"] Q --> Q2["Step 6b: .ui-quality.yml, axe, component gallery,\nUI screenshot helper, sample screen spec"] Q2 --> R{"Step 7: storybook: yes?"} R -- yes --> S["Run storybook init;\nreconcile vitest.config.ts project split"] R -- no --> T S --> T{"Step 8: sonar cloud/self-hosted?"} T -- yes --> U[Write sonar-project.properties] T -- no --> V[Remove or flag existing sonar-project.properties] U --> W V --> W["Step 9: Wire npm scripts; add tsconfig.e2e.json;\nfix tsc -b vs tsc --noEmit gotcha"] W --> X["Run typecheck, lint, format,\ntest, coverage, build, e2e"] X --> Y["Step 10: Report per-artifact actions,\nmismatches, warnings"]

Dependencies

Invokes

None — iru-setup-react-web is a leaf skill; it does not call any other skill in this catalog.

Invoked by

Also runnable stand-alone.

Related agents

None — this skill runs to completion in a single context; it is iru-setup-typescript-repository that dispatches to it via iru-isolated-skill-executor.

Source

SKILL.md on GitHub — the file this page was generated from.