Local Development Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• vite.config.js
• CLAUDE.md
• AGENTS.md
• test/README.md

The Local Development Setup for the RoundingWell frontend project is designed to provide developers with a robust environment for building, testing, and debugging the application. The system utilizes modern web tooling, including Vite for fast development serving and HMR (Hot Module Replacement), npm for package management, and Cypress for UI and component testing.

The environment is built to interface with both local and remote backend environments. Developers typically run the Vite development server locally while proxying API requests to a remote AWS development organization or a local backend instance. This setup ensures that the frontend can be developed in isolation while still having access to live or mocked data services.

Sources: README.md:1-85, CLAUDE.md:1-15, vite.config.js:100-140

Prerequisites and Installation

The project requires a specific Node.js environment and uses npm as the primary package manager. It is recommended to use nvm (Node Version Manager) to ensure the correct version of Node is active.

System Requirements

Requirement	Description
Node.js	Version specified in .nvmrc (managed via nvm use)
npm	Standard package manager for dependency installation
Font Awesome Pro	Requires a global license setup for npm

Initial Configuration

1. Node Version: Use nvm use to switch to the project's supported Node version.
2. Install Dependencies: Run npm i to install all required packages defined in package.json.
3. Font Awesome: Developers must log into the Font Awesome documentation page to obtain and configure the license needed for Pro icons.

Sources: README.md:10-25, README.md:105-115, package.json:1-10

Backend Connection

Developers can choose to develop against a local backend or a remote AWS-hosted organization. This is configured via environment variables and CLI commands.

Remote AWS Setup

To develop against a remote AWS dev organization, the following steps are required:

1. Deploy Organization: Use the console to deploy a specific organization slug (e.g., bin/console deploy:dev <slug>).
2. Prepare Clinician: After first login, use the remote console to prepare a clinician account for testing.
3. API URL Configuration: Create a .env file in the project root and set the VITE_DEV_API_URL.

VITE_DEV_API_URL=https://<organization-slug>.roundingwell.dev

API Proxy Flow

The local development server proxies requests starting with /api to the configured backend.

The proxy behavior changes based on whether VITE_DEV_API_URL is set: if unset, it defaults to http://localhost:8080 and rewrites the /api prefix.

Sources: README.md:70-85, vite.config.js:125-135

Development Server and Tooling

The core development experience is driven by Vite. The project defines several npm scripts to manage the lifecycle of the local server.

Primary Commands

• npm run dev: Starts the Vite development server (default port 8081). Includes HMR and proxying.
• npm run stop: Attempts to kill existing Vite processes and clear the .vite cache. This is useful when the server fails to release a port.
• npm run lint: Executes eslint, stylelint, and editorconfig-checker to ensure code quality.

Shared Runtime Development

A custom Vite plugin, shared-runtime-dev-plugin, is used during local development to handle requests for shared modules. It intercepts request paths defined in SHARED_RUNTIME_DEV_MODULES and transforms them via the Vite server to serve them as application/javascript.

Sources: README.md:88-103, package.json:28-65, vite.config.js:52-82

Testing Environment

The development setup includes integrated support for both unit and functional UI testing.

Cypress (UI & Component Testing)

The project uses Cypress for functional testing. It is configured to stub server data, ensuring tests remain isolated from backend changes.

• Command: npm test runs Vite in test mode and opens the Cypress GUI.
• Component Tests: Located next to source files as src/**/foo.cy.js.
• Integration Tests: Located under test/integration/**.

Vitest (Unit Testing)

Unit tests for utilities and pure functions are handled by Vitest.

• Command: npm run test:unit.
• Location: Suites live next to source files as src/**/foo.test.js.

Test Environment Flow

Summary of Configuration

The following table summarizes the primary configuration parameters for the local environment.

Variable/Setting	Default Value	Description
VITE_DEV_API_URL	http://localhost:8080	The target URL for API proxying
Dev Server Port	8081	Standard port for npm run dev
Test Server Port	8090	Port used during npm test
_DEVELOP_	true	Feature flag enabled during development
_PRODUCTION_	false	Disabled during local development

Sources: README.md:150-155, vite.config.js:115-125

Local development setup is a streamlined process focusing on Node versioning and environment variable configuration to bridge the frontend with necessary backend services. By leveraging Vite and Cypress, the environment provides immediate feedback via HMR and robust testing capabilities for business logic and UI components.