Local Setup

This guide will walk you through setting up labelWise on your local machine for development.

Prerequisites

Node.js and npm

labelWise requires Node.js to run the development server and build tools. Required version:

Node.js 18.0 or higher (20.x LTS recommended)
npm 9.0 or higher (comes with Node.js)

Check your current version:

node --version
npm --version

Installation: If you need to install or update Node.js:

macOS/Linux: Use nvm (Node Version Manager)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

Windows: Download from nodejs.org or use nvm-windows

Git

You’ll need Git to clone the repository:

git --version

Install Git from git-scm.com if needed.

Getting the Code

Clone the Repository

git clone https://github.com/YOUR_USERNAME/labelWise.git
cd labelWise

If you’re contributing, fork the repository first and clone your fork:

git clone https://github.com/YOUR_USERNAME/labelWise.git
cd labelWise
git remote add upstream https://github.com/ORIGINAL_OWNER/labelWise.git

Installing Dependencies

Install all required npm packages:

npm install

This will install:

React 19 and React DOM - UI framework
TypeScript - Type checking
Vite - Build tool and dev server
Tailwind CSS v4 - Styling
ESLint - Code linting
And all other dependencies from package.json

The installation process downloads packages from npm and may take 1-3 minutes depending on your internet connection.

Running the Development Server

Start the Vite development server:

npm run dev

Expected output:

  VITE v7.3.1  ready in 423 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

Open your browser and navigate to http://localhost:5173

Development Server Features

Hot Module Replacement (HMR) - Changes appear instantly without full page reload
Fast Refresh - React component state preserved during updates
TypeScript checking - Type errors shown in the browser and terminal
Error overlay - Build errors displayed directly in the browser

Available npm Scripts

labelWise provides several npm scripts for development:

`npm run dev`

Starts the Vite development server with HMR.

Port: 5173 (default)
Use case: Daily development work

`npm run build`

Builds the application for production.

npm run build

This runs two steps:

TypeScript compilation - tsc -b checks types across all TypeScript files
Vite build - Bundles the application into dist/ directory

Output location: dist/

`npm run lint`

Runs ESLint to check code quality.

npm run lint

Fix auto-fixable issues:

npm run lint -- --fix

`npm run preview`

Serves the production build locally for testing.

npm run build
npm run preview

Port: 4173 (default)
Use case: Testing the production build before deployment

Project File Structure

After installation, your project structure should look like this:

labelWise/
├── node_modules/           # Installed dependencies (git-ignored)
├── dist/                   # Production build output (git-ignored)
├── public/                 # Static assets served as-is
│   └── labelWise-all.png
├── src/
│   ├── App.tsx            # Main application component
│   ├── main.tsx           # Application entry point
│   ├── index.css          # Global styles
│   ├── features/
│   │   └── labelwise/
│   │       ├── components/
│   │       ├── constants.ts
│   │       ├── types.ts
│   │       └── utils/
│   ├── components/
│   │   └── ui/            # Reusable UI components
│   ├── lib/
│   │   └── utils.ts       # Helper utilities
│   └── assets/            # Images and static files
├── package.json           # Dependencies and scripts
├── package-lock.json      # Locked dependency versions
├── tsconfig.json          # TypeScript configuration
├── tsconfig.app.json      # App-specific TypeScript config
├── vite.config.ts         # Vite bundler configuration
├── eslint.config.js       # ESLint rules
├── tailwind.config.js     # Tailwind CSS configuration
└── README.md              # Project overview

IDE Setup

VS Code (Recommended)

labelWise works best with Visual Studio Code. Install these extensions:

Essential Extensions

ESLint (dbaeumer.vscode-eslint)
- Real-time linting in the editor
- Auto-fix on save
Prettier - Code formatter (esbenp.prettier-vscode)
- Consistent code formatting
- Format on save
Tailwind CSS IntelliSense (bradlc.vscode-tailwindcss)
- Autocomplete for Tailwind classes
- Hover previews of styles
TypeScript and JavaScript Language Features (built-in)
- TypeScript IntelliSense
- Auto-imports

Recommended Extensions

Error Lens (usernamehw.errorlens)
- Inline error messages
Auto Rename Tag (formulahendry.auto-rename-tag)
- Automatically rename paired HTML/JSX tags
Path Intellisense (christian-kohler.path-intellisense)
- Autocomplete for file paths

VS Code Settings

Create or update .vscode/settings.json:

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true,
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["cn\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
  ]
}

Other IDEs

labelWise should work with any modern IDE that supports TypeScript and React:

WebStorm - Excellent TypeScript support out of the box
Sublime Text - Install TypeScript and ESLint plugins
Vim/Neovim - Use CoC or built-in LSP with typescript-language-server

Debugging

Browser DevTools

The development build includes full source maps for debugging:

Open browser DevTools (F12)
Go to the Sources tab
Navigate to webpack:// → src/
Set breakpoints in your TypeScript files

VS Code Debugging

Create .vscode/launch.json for debugging in VS Code:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "Launch Chrome",
      "url": "http://localhost:5173",
      "webRoot": "${workspaceFolder}/src",
      "sourceMapPathOverrides": {
        "webpack:///./*": "${webRoot}/*"
      }
    }
  ]
}

Then press F5 to start debugging with breakpoints in VS Code.

Common Debugging Scenarios

React DevTools: Install the React DevTools browser extension:

Inspect component state, props, and hooks in the React tab of DevTools. TypeScript Errors: If you see TypeScript errors in the terminal:

Check the error message and file location
Run npm run build to see all errors at once
Use your IDE’s TypeScript features to see inline errors

Tailwind Classes Not Working:

Ensure @tailwindcss/vite plugin is loaded in vite.config.ts
Check that index.css imports Tailwind directives
Restart the dev server (Ctrl+C, then npm run dev)

Troubleshooting

Port Already in Use

If port 5173 is already in use:

npm run dev -- --port 3000

Or kill the process using port 5173:

# macOS/Linux
lsof -ti:5173 | xargs kill -9

# Windows (PowerShell)
Get-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess | Stop-Process

Module Not Found Errors

If you see module import errors:

rm -rf node_modules package-lock.json
npm install

TypeScript Configuration Issues

If path aliases (@/) don’t work:

Ensure tsconfig.json has the correct baseUrl and paths
Restart your IDE to reload TypeScript configuration
Run npx tsc --showConfig to verify configuration

Build Failures

If npm run build fails:

Check for TypeScript errors: npx tsc --noEmit
Ensure all dependencies are installed: npm install
Clear Vite cache: rm -rf node_modules/.vite
Check Node.js version: node --version (must be 18+)

Next Steps

Now that you have labelWise running locally:

Explore the code - Start with src/App.tsx to understand the application flow
Read the architecture - Check Architecture for technical details
Make changes - Try modifying the UI or adding a feature
Contribute - See Contributing for guidelines

Getting Help

If you encounter issues not covered here:

Check GitHub Issues for similar problems
Search the Vite documentation
Ask in the project’s discussion forum or chat
Review the Contributing guide for support channels

Happy coding!

Get Started

Core Features

Guides

Development

Prerequisites

Node.js and npm

Git

Getting the Code

Clone the Repository

Installing Dependencies

Running the Development Server

Development Server Features

Available npm Scripts

`npm run dev`

`npm run build`

`npm run lint`

`npm run preview`

Project File Structure

IDE Setup

VS Code (Recommended)

Essential Extensions

Recommended Extensions

VS Code Settings

Other IDEs

Debugging

Browser DevTools

VS Code Debugging

Common Debugging Scenarios

Troubleshooting

Port Already in Use

Module Not Found Errors

TypeScript Configuration Issues

Build Failures

Next Steps

Getting Help

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Development

​Prerequisites

​Node.js and npm

​Git

​Getting the Code

​Clone the Repository

​Installing Dependencies

​Running the Development Server

​Development Server Features

​Available npm Scripts

​npm run dev

​npm run build

​npm run lint

​npm run preview

​Project File Structure

​IDE Setup

​VS Code (Recommended)

​Essential Extensions

​Recommended Extensions

​VS Code Settings

​Other IDEs

​Debugging

​Browser DevTools

​VS Code Debugging

​Common Debugging Scenarios

​Troubleshooting

​Port Already in Use

​Module Not Found Errors

​TypeScript Configuration Issues

​Build Failures

​Next Steps

​Getting Help

Build docs developers (and LLMs) love

Prerequisites

Node.js and npm

Git

Getting the Code

Clone the Repository

Installing Dependencies

Running the Development Server

Development Server Features

Available npm Scripts

`npm run dev`

`npm run build`

`npm run lint`

`npm run preview`

Project File Structure

IDE Setup

VS Code (Recommended)

Essential Extensions

Recommended Extensions

VS Code Settings

Other IDEs

Debugging

Browser DevTools

VS Code Debugging

Common Debugging Scenarios

Troubleshooting

Port Already in Use

Module Not Found Errors

TypeScript Configuration Issues

Build Failures

Next Steps

Getting Help