react-app-scaffold-and-runtime

name

react-app-scaffold-and-runtime

description

Use when creating, modernizing, or production-hardening a standalone React SPA after frontend architecture is approved or intentionally deferred. Produces a production-ready app shell with Vite (or Webpack) project layout, environment and profile handling, top-level and route-level error boundaries, a structured logging client, RUM and error-reporting wiring, the auth provider/wrapper baseline downstream skills extend, CSP and security-header posture via host config, and container or static-CDN packaging. Do not use for routing topology, rendering strategy, state or data-fetching wiring, design-system integration, performance budgeting, or SSR/meta-framework scaffolding; use the other react archetype skills or the nextjs stack instead.

React App Scaffold and Runtime

When to use

Invoke when starting a new standalone React SPA, standardizing an internal React app baseline, modernizing a legacy Create-React-App or Webpack app, or preparing a React app for container or CDN deployment.

Do not use for: routing/rendering decisions (use react-routing-and-rendering-strategy), state or data-fetching wiring (use react-state-management-and-data-fetching), design-system or accessibility integration (use react-design-system-and-accessibility), perf budgeting (use react-performance-and-delivery-optimization), or any SSR/RSC/server-action scaffolding (that is meta-framework territory — use the nextjs stack).

Inputs

Required:

• App name and the business capability it serves.
• Approved frontend-architecture.md, or explicit confirmation that frontend architecture is intentionally deferred.

Optional:

• Approved architecture/security decisions on auth provider, session model, and token strategy.
• Bundler preference (Vite default, Webpack on constraint).
• Deployment target (static CDN, container, edge static host).
• RUM and error-reporting vendor (Sentry, Datadog, none).
• Node version and package manager.
• CSP and security-header constraints from the hosting platform.
• Monorepo vs single-repo placement.

Operating rules

• Never generate tutorial-grade scaffolding. Assume multiple environments, observability, CDN or container deployment, CSP enforcement, and operational ownership.
• Consume the architecture; do not invent it. Rendering mode, routing topology, state model, design-system seam, and perf budgets belong to other archetypes and to frontend-architecture. If frontend-architecture.md is missing a decision this scaffold needs (auth provider, runtime target), pause and raise an ADR candidate against frontend-architecture or architecture/security.
• This skill owns the auth provider/wrapper baseline only (e.g. AuthProvider/SessionContext shell, env-aware client ID, CSP headers). Token storage/refresh, protected-route gates, and accessible auth UIs belong to other react archetypes — scaffold the seam, do not implement the flow.
• Secure by default: no secrets in the bundle, env-injected config at deploy time (not build-time-baked secrets), a CSP that is not unsafe-inline/unsafe-eval without a documented exception, and security headers defined via host config.
• Observability is mandatory in the baseline: a structured logging client, RUM (web-vitals) wiring, and error-reporting with release/environment tagging and a top-level error boundary that reports.
• Error boundaries are layered: one top-level boundary that reports and renders a safe fallback, plus the seam for route-level boundaries the routing skill will populate.
• Config is environment-agnostic at build time. The same artifact runs in every environment; configuration arrives via runtime injection (window.__ENV__, /config.json, or platform env), never via per-environment builds.
• Confirm the target directory before writing files. Recommend apps/<app-name>/ in a monorepo or repo root for a single-app repo. Refuse to write into a plugin/skill repository (any directory containing skills/, standards/, architecture-patterns/, or marketplace.json) without explicit user override.
• A scaffold that does not build and does not pass its smoke test is not done. Run the build and a baseline render/e2e smoke before declaring completion; fix and re-run on failure.

Output contract

The generated app shell MUST conform to:

• security-standards — no secrets in the bundle, CSP and security headers defined, token storage discipline deferred to the data-fetching skill but the provider seam not leaking credentials.
• observability-standards — RUM and error reporting wired with environment/release tags, browser-to-backend trace correlation seam present.
• deployment-standards — env-agnostic build, runtime config injection, CDN/edge or container artifact.
• naming-conventions — app name, env vars, asset and image naming.

Upstream contract: frontend-architecture.md is the source of truth for runtime target and the auth provider decision; architecture/security is the source of truth for the auth provider, session model, and token strategy. If either is silent on a decision this scaffold needs, pause and raise an ADR candidate rather than guessing.

Process

1. Gather context: app name, business capability, target directory, bundler, deployment target, RUM/error vendor, Node version, package manager, and the auth provider decision from skills/architecture/security. Recommend Vite, current LTS Node, and static-CDN deployment unless constraints say otherwise. Verify the target directory is not a plugin/skill repository.
2. Generate the project layout: Vite (or Webpack) configuration, TypeScript config, directory structure (capability- or feature-oriented), entry point, and the app root with a single mount.
3. Generate environment and profile handling: typed env access, the runtime-config injection mechanism (no build-time secrets), and per-environment config documentation.
4. Generate the layered error-boundary baseline: a reporting top-level boundary with a safe fallback UI, plus the seam (provider/exported boundary component) for route-level boundaries the routing skill will use.
5. Generate the observability baseline: a structured logging client (level-aware, environment-aware), web-vitals RUM wiring, error-reporting init with release and environment tags, and the trace-correlation header seam for browser-to-backend.
6. Generate the auth provider/wrapper baseline only: the provider shell and context seam named per the architecture/security decision, env-aware client/app ID handling, and CSP/security headers via host config. Explicitly leave token storage/refresh and route gates as documented seams for the data-fetching and routing skills.
7. Generate packaging: a static-CDN build (with cache-control guidance) or a container image (env-agnostic, runtime config injected), plus ignore files and a .env.example with no real secrets.
8. Generate local-run and configuration documentation: how to run, the environment variables, the runtime-config contract, and the explicit list of seams downstream archetypes will fill.
9. Build verification (mandatory): run the production build and a baseline smoke test (render + minimal e2e). If e2e tooling is unavailable, document the skipped check in the README rather than declaring success silently. Fix and re-run on failure.
10. Validate against security-standards, observability-standards, deployment-standards, and naming-conventions. Revise until all pass or explicitly document any unresolved gap.

Outputs

Required:

• React app source tree with bundler and TypeScript configuration.
• Environment/profile handling with runtime config injection.
• Layered error-boundary baseline (top-level reporting boundary + route-boundary seam).
• Observability baseline: structured logging client, web-vitals RUM, error-reporting init.
• Auth provider/wrapper baseline (seam only) per the architecture/security decision.
• Packaging: static-CDN build or container image, ignore files, .env.example.
• Local-run documentation listing environment variables and the seams downstream skills fill.

Output rules:

• Generated files are functional, not placeholder-heavy.
• No secrets in the bundle, in .env.example, or in committed config.
• The auth baseline is a seam, not a flow — token logic and gates are explicitly deferred.
• The same build artifact must run in every environment via runtime config.

Quality checks

• The production build succeeds and the baseline smoke test passes (or the gap is explicitly documented).
• No secrets appear in the bundle, .env.example, or committed config.
• A CSP and security headers are defined; unsafe-inline/unsafe-eval are absent or have a documented exception.
• A top-level error boundary reports to the error-reporting sink and renders a safe fallback.
• web-vitals RUM and error reporting are wired with environment and release tags.
• Configuration is injected at runtime; no per-environment build or build-time secret exists.
• The auth provider/wrapper baseline is a seam tied to a named architecture/security decision; token storage and route gates are explicitly deferred to the relevant react skills.
• The README lists the seams downstream archetypes (routing, state/data, design-system, performance) are expected to fill.

References

• Upstream: architecture/frontend-architecture, architecture/security.
• Related react archetype skills (extend this baseline): react-routing-and-rendering-strategy, react-state-management-and-data-fetching, react-design-system-and-accessibility, react-performance-and-delivery-optimization.
• Compatible patterns: microservices (BFF-backed SPA), cqrs, real-time-systems.