Skip to main content

​
Quick Start Guide

Get the RAADS-R Self-Host application up and running in minutes. This guide will take you from clone to running app.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js version 18 or higher
  • npm (comes with Node.js)
  • Git for cloning the repository
Check your Node.js version with node --version. If you need to install or update Node.js, visit nodejs.org.

​
Installation Steps

1

Clone the repository

Clone the RAADS-R Self-Host repository to your local machine:
git clone <repository-url>
cd raads-r-self-host
2

Install dependencies

Install the required npm packages:
npm install
This installs:
  • React 19.2.0 and React DOM
  • Vite 7.3.1 for development and building
  • Tailwind CSS v4 for styling
  • TypeScript for type safety
  • Vitest for testing
3

Start the development server

Launch the local development server:
npm run dev
The application will be available at http://localhost:5173
4

Open in your browser

Navigate to http://localhost:5173 in your web browser. You should see the RAADS-R landing page.

​
Verify Installation

Once the development server is running, verify everything works:
  1. Landing page loads: You should see the RAADS-R questionnaire introduction
  2. Dark mode toggle: Click the theme toggle to switch between light and dark modes
  3. Start questionnaire: Click to begin and verify the first question loads
  4. Navigate questions: Test the previous/next buttons
The development server supports hot module replacement (HMR), so changes to the source code will automatically reload in the browser.

​
Available Commands

Once installed, you have access to these npm scripts: 
npm run dev
# Starts Vite dev server on localhost:5173
# Hot module replacement enabled

​
Build for Production

When you’re ready to deploy, create a production build:
1

Build the application

npm run build
This compiles TypeScript and creates optimized production files in the dist/ directory.
2

Preview locally (optional)

npm run preview
Test the production build on your local machine before deploying.
3

Deploy the dist/ folder

Deploy the contents of the dist/ folder to your hosting provider of choice.See the Deployment Guide for detailed deployment options.

​
Testing the Application

The project includes comprehensive tests to ensure scoring accuracy: 
npm run test
The test suite includes:
  • 62 total tests validating all scoring logic
  • Golden test vectors for uniform response patterns (189, 51, 143, 97)
  • Cross-validation between two independent scoring engines
  • Dataset structural tests confirming all 80 items are accounted for
  • No overlap validation across the four clinical domains
Run tests before deploying to ensure the scoring implementation is correct.

​
Troubleshooting

​
Port 5173 already in use

If you see an error that port 5173 is already in use: 
# Kill the process using port 5173
lsof -ti:5173 | xargs kill -9

# Or specify a different port
npm run dev -- --port 3000

​
Build fails with TypeScript errors

Ensure you’re using the correct Node.js version: 
node --version  # Should be 18+
Clear node_modules and reinstall: 
rm -rf node_modules package-lock.json
npm install

​
Module not found errors

If you see module resolution errors, try: 
npm install
npm run build

​
Project Structure

Understanding the project layout: 
raads-r-self-host/
├── src/
│   ├── components/     # React components (Landing, Quiz, Results, etc.)
│   ├── data/          # dataset.json with all 80 RAADS-R items
│   ├── engine/        # Scoring logic and validation
│   ├── hooks/         # Custom React hooks (useQuizState, useDarkMode)
│   ├── utils/         # Export utilities (JSON, CSV, PDF)
│   ├── App.tsx        # Main application component
│   └── main.tsx       # Application entry point
├── public/            # Static assets
├── dist/              # Production build output (generated)
├── package.json       # Dependencies and scripts
├── vite.config.ts     # Vite configuration
└── tsconfig.json      # TypeScript configuration

​
Next Steps

Deployment Options

Learn about deploying to Netlify, Vercel, GitHub Pages, and more.

Customization

Customize the questionnaire and UI to fit your needs.

Build docs developers (and LLMs) love

Get started for freeTalk to us