Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js v18 or higher
  • npm v9 or higher (comes with Node.js)
  • A code editor (VS Code recommended)
  • Git (for version control)

​
Clone the Repository

First, clone the repository to your local machine: 
git clone https://github.com/yourusername/raads-r-self-host.git
cd raads-r-self-host

​
Installation

1

Install Dependencies

Install all required npm packages:
npm install
This will install all dependencies listed in package.json, including:
  • React 19.2.0
  • Vite 7.3.1
  • TypeScript 5.9.3
  • Tailwind CSS v4.2.1
  • Vitest 4.0.18
2

Start Development Server

Run the development server:
npm run dev
The application will be available at http://localhost:5173
The dev server includes hot module replacement (HMR), so your changes will appear instantly without a full page reload.
3

Verify Installation

Open your browser and navigate to http://localhost:5173. You should see the RAADS-R questionnaire landing page.Try toggling dark mode and navigating through the interface to ensure everything works correctly.

​
Available Scripts

The project includes several npm scripts for development and testing: 
npm run dev

​
Script Details

  • npm run dev - Starts Vite development server with HMR on port 5173
  • npm run build - Compiles TypeScript and builds production bundle to dist/
  • npm run lint - Runs ESLint on the codebase to check for code quality issues
  • npm run preview - Serves the production build locally for testing
  • npm run test - Runs all Vitest tests once and exits
  • npm run test:watch - Runs tests in watch mode, re-running on file changes

​
Development Workflow

1

Make Changes

Edit files in the src/ directory. The dev server will automatically reload.
2

Run Tests

Before committing, run the test suite:
npm run test
Ensure all 62+ tests pass. The test suite includes:
  • Scoring algorithm validation
  • Dataset structural integrity checks
  • Golden test vectors for uniform response patterns
3

Lint Your Code

Check for code quality issues:
npm run lint
4

Build for Production

Test the production build locally:
npm run build
npm run preview

​
Environment Configuration

This project has no environment variables or external configuration. Everything runs client-side with no backend required.
The application is fully offline-first and requires no API keys, database connections, or external services.

​
Troubleshooting

​
Port Already in Use

If port 5173 is already in use, Vite will automatically try the next available port (5174, 5175, etc.). Check the terminal output for the actual URL.

​
Type Errors

If you encounter TypeScript errors: 
# Rebuild TypeScript declarations
npm run build

​
Module Not Found

If you see module resolution errors: 
# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

​
Tests Failing

If tests fail unexpectedly: 
# Run tests in verbose mode
npm run test -- --reporter=verbose
Use npm run test:watch during development to get instant feedback as you write code.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us