Skip to Content
🚀 Getting StartedRunning Locally

Last Updated: 4/7/2026

Running Locally Without Docker

This guide shows you how to run Where Did They Go? directly on your machine without Docker. You’ll manually install dependencies and start the client and server in separate terminal windows. This approach gives you full control over the development environment and works well if you prefer not to use containers.

Prerequisites

Install the following software on your system:

  1. Node.js – Version 20.19.0 or higher, or version 22.12.0 or higher

    • Download from nodejs.org 
    • Verify installation: node --version

  2. npm – Comes bundled with Node.js

    • Verify installation: npm --version

The client’s package.json specifies the required Node.js versions in the engines field: "node": "^20.19.0 || >=22.12.0". Using an incompatible version may cause build errors.

Step 1: Clone the Repository

Open a terminal and clone the project:

git clone https://github.com/ksu-cs/development-project-ksds.git
cd development-project-ksds

Step 2: Install Server Dependencies

Navigate to the server directory and install packages:

cd server
npm install

This installs Express, nodemon, compression, cookie-parser, D3, and other server dependencies. The installation typically takes 30–60 seconds.

Step 3: Install Client Dependencies

Open a new terminal window (keep the first one open for later), navigate to the client directory, and install packages:

cd client
npm install

This installs Vue 3, Vite, D3, Pinia, Vue Router, and development tools like ESLint and Vitest. The client has more dependencies than the server, so installation may take 1–2 minutes.

Step 4: Start the Server

In your first terminal (in the server/ directory), start the development server:

npm run dev

This command runs nodemon ./bin/www, which:

  • Starts the Express server on port 3000
  • Watches for file changes and automatically restarts the server
  • Serves static JSON/GeoJSON data files from the public/ directory
  • Renders the application’s index page

You should see output similar to:

[nodemon] starting `node ./bin/www`
Server listening on port 3000

Leave this terminal running.

Step 5: Start the Client

In your second terminal (in the client/ directory), start the development client:

npm run dev

This command runs vite --host 0.0.0.0, which:

  • Starts the Vite development server on port 5173
  • Enables hot module replacement (HMR) for instant updates during development
  • Serves the Vue 3 application with optimized build tooling

You should see output like:

VITE v7.3.1  ready in 450 ms

➜  Local:   http://localhost:5173/
➜  Network: http://192.168.1.100:5173/

Leave this terminal running as well.

Step 6: Verify the Application

Open your browser and navigate to:

You should see the Kansas map with county borders, a timeline slider set to 1860, and a play button. Try dragging the slider or clicking a county to verify everything works.

Running Tests

The client includes unit tests written with Vitest. To run them:

cd client
npm run test:unit

This executes all test files in the client/ directory and displays results in the terminal. Tests run in watch mode by default, re-running when you modify source files.

Linting and Formatting

The client uses ESLint and Prettier for code quality:

Run ESLint with Auto-Fix

cd client
npm run lint

This command runs eslint . --fix, which checks all JavaScript and Vue files for style violations and automatically fixes issues where possible.

Format Code with Prettier

cd client
npm run format

This runs prettier --write src/, reformatting all source files according to the project’s Prettier configuration.

Lint and Format Together

cd client
npm run lint:format

This convenience script runs both ESLint and Prettier in sequence.

Building for Production

To create an optimized production build of the client:

cd client
npm run build

This runs vite build, which:

  • Bundles and minifies all JavaScript and CSS
  • Optimizes assets for production
  • Outputs the built files to client/dist/

To preview the production build locally:

cd client
npm run preview

This serves the built files from client/dist/ so you can test the production version before deployment.

Stopping the Application

To stop the development servers:

  1. In each terminal window, press Ctrl+C
  2. Wait for the processes to terminate
  3. Close the terminal windows

Troubleshooting

Port already in use: If port 3000 or 5173 is occupied, stop the conflicting application or modify the port in the respective package.json scripts.

Module not found errors: Ensure you ran npm install in both the client/ and server/ directories.

Node version mismatch: Verify your Node.js version meets the requirements: node --version should show 20.19.0+ or 22.12.0+.

Build errors: Try deleting node_modules/ and package-lock.json in both directories, then run npm install again.

What’s Next

With your local development environment running:

Running With DockerAdding A Data Component