Installation Guide

This guide provides detailed instructions for installing and configuring SAAC Frontend, including system requirements, multiple installation methods, and troubleshooting common issues.

System Requirements

Before installing SAAC Frontend, ensure your system meets these requirements:

Required Software

Node.js

Version 18.0.0 or higherLTS version recommended for production use

Package Manager

One of:

npm (comes with Node.js)
yarn 1.22.0+
pnpm 8.0.0+

Git

Version 2.0 or higherRequired for cloning the repository

Code Editor

Recommended:

VS Code with ESLint extension
WebStorm with TypeScript support

Operating System Support

macOS: 10.15 (Catalina) or later
Windows: 10 or later (PowerShell or WSL2 recommended)
Linux: Ubuntu 20.04+, Debian 10+, or equivalent

For Windows users, we recommend using WSL2 (Windows Subsystem for Linux) for the best development experience and compatibility with Node.js tooling.

Installation Steps

Verify Node.js Installation

First, confirm Node.js is installed and meets the version requirement:

node --version

Expected output: v18.0.0 or higher (e.g., v20.11.0, v22.1.0)If Node.js is not installed or the version is too old:

brew install node

Clone the Repository

Clone the SAAC Frontend template to your local machine:

git clone <repository-url> saac-frontend
cd saac-frontend

Replace <repository-url> with your actual Git repository URL.

If you’re creating a new project, you can also fork the repository or download it as a ZIP file.

Install Dependencies

Install all required packages using your preferred package manager:

npm install

This installs the following key dependencies:Production Dependencies:

[email protected] - Core React library
[email protected] - React DOM renderer
[email protected] - Utility-first CSS framework
@tailwindcss/[email protected] - Tailwind CSS Vite plugin

Development Dependencies:

[email protected] - Build tool and dev server
[email protected] - TypeScript compiler
@vitejs/[email protected] - React plugin with SWC
[email protected] - JavaScript/TypeScript linter
@types/[email protected] - TypeScript types for React
@types/[email protected] - TypeScript types for React DOM

The installation may take 1-3 minutes depending on your internet connection and system performance.

Verify Installation

Confirm everything is installed correctly by checking the node_modules directory:

ls node_modules | wc -l

You should see around 200-300 packages installed (including all transitive dependencies).Also verify the TypeScript compiler is available:

npx tsc --version

Expected output: Version 5.8.3

Start Development Server

Launch the development server to ensure everything works:

npm run dev

If successful, you’ll see output like:

VITE v7.1.2  ready in 342 ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose

Open http://localhost:5173 in your browser to see the application running.

Configuration Overview

SAAC Frontend comes pre-configured with optimal settings. Here’s what’s included:

Vite Configuration

The vite.config.ts file configures the build tool:

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react-swc'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
})

Key Features:

React plugin with SWC for fast refresh
Tailwind CSS integrated via Vite plugin
Optimized for both development and production

TypeScript Configuration

The project uses a TypeScript project references setup with:

tsconfig.json - Root configuration
tsconfig.app.json - Application code settings
tsconfig.node.json - Build scripts settings

This provides optimal type checking and compilation performance.

ESLint Configuration

Linting is configured in eslint.config.js with:

React-specific rules (eslint-plugin-react-hooks, eslint-plugin-react-refresh)
TypeScript integration (typescript-eslint)
Modern flat config format

Package Manager Comparison

Choose the package manager that best fits your workflow:

Feature	npm	yarn	pnpm
Speed	Good	Fast	Fastest
Disk Usage	Standard	Standard	Minimal
Lock File	package-lock.json	yarn.lock	pnpm-lock.yaml
Workspaces	Yes	Yes	Yes
Node.js Bundled	Yes	No	No

All three package managers work equally well with SAAC Frontend. npm is included with Node.js, while yarn and pnpm must be installed separately.

Installing Alternative Package Managers

npm install -g yarn

Environment Setup

Editor Configuration (VS Code)

For the best development experience with VS Code:

Install recommended extensions:
- ESLint (dbaeumer.vscode-eslint)
- TypeScript and JavaScript Language Features (built-in)
- Tailwind CSS IntelliSense (bradlc.vscode-tailwindcss)
Configure settings (.vscode/settings.json):

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

Git Configuration

Set up Git to ignore build artifacts and dependencies: The included .gitignore already covers:

node_modules/ - Dependencies
dist/ - Production builds
.env*.local - Local environment variables
Editor-specific files

Building for Production

Once installation is complete, you can create production builds:

Run the build command

npm run build

This command:

Runs TypeScript compiler (tsc -b) for type checking
Builds optimized assets with Vite
Outputs files to dist/ directory

Preview the build

Test the production build locally:

npm run preview

This serves the dist/ folder on http://localhost:4173

Troubleshooting

Common Installation Issues

npm install fails with permission errors

Problem: On Unix systems, you may encounter EACCES errors.Solutions:

Use nvm to manage Node.js (recommended):

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

Or fix npm permissions:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Never use sudo npm install as this can cause security issues.

Port 5173 is already in use

Problem: Another application is using the default Vite port.Solutions:

Vite will automatically use the next available port (5174, 5175, etc.)
Or specify a custom port:

npm run dev -- --port 3000

Or kill the process using the port:

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

# Windows
netstat -ano | findstr :5173
taskkill /PID <PID> /F

TypeScript errors in editor but build works

Problem: Editor shows type errors but npm run build succeeds.Solutions:

Restart TypeScript server in VS Code:
- Press Cmd/Ctrl + Shift + P
- Type “TypeScript: Restart TS Server”
Ensure editor uses workspace TypeScript:
- Check status bar shows “TypeScript 5.8.3”
- If not, click version number and select “Use Workspace Version”
Delete TypeScript cache:

rm -rf node_modules/.vite

Slow installation or dependency resolution

Problem: npm install takes a very long time.Solutions:

Clear npm cache:

npm cache clean --force

Try a faster package manager:

npm install -g pnpm
pnpm install

Use a faster registry mirror (if in certain regions):

npm config set registry https://registry.npmjs.org/

Module not found errors

Problem: Import statements show “Cannot find module” errors.Solutions:

Verify all dependencies are installed:

rm -rf node_modules package-lock.json
npm install

Check import paths use correct casing (file systems are case-sensitive on Linux/macOS)
Ensure TypeScript paths are configured correctly in tsconfig.json

Getting Help

If you encounter issues not covered here:

Check the console: Look for error messages in terminal and browser console
Verify versions: Ensure Node.js, npm, and dependencies match requirements
Search GitHub issues: Check if others have reported similar problems
Clean install: Try removing node_modules and reinstalling

Next Steps

With SAAC Frontend installed, you’re ready to start building:

Quickstart Tutorial

Follow our quickstart guide to build your first feature

Project Structure

Learn how the codebase is organized

Development Workflow

Understand the development and build process

Deployment

Deploy your application to production

Get Started

Development

Configuration

Deployment

Installation

Installation Guide

System Requirements

Required Software

Node.js

Package Manager

Git

Code Editor

Operating System Support

Installation Steps

Configuration Overview

Vite Configuration

TypeScript Configuration

ESLint Configuration

Package Manager Comparison

Installing Alternative Package Managers

Environment Setup

Editor Configuration (VS Code)

Git Configuration

Building for Production

Troubleshooting

Common Installation Issues

Getting Help

Next Steps

Quickstart Tutorial

Project Structure

Development Workflow

Deployment

Build docs developers (and LLMs) love

Get Started

Development

Configuration

Deployment

​Installation Guide

​System Requirements

​Required Software

Node.js

Package Manager

Git

Code Editor

​Operating System Support

​Installation Steps

​Configuration Overview

​Vite Configuration

​TypeScript Configuration

​ESLint Configuration

​Package Manager Comparison

​Installing Alternative Package Managers

​Environment Setup

​Editor Configuration (VS Code)

​Git Configuration

​Building for Production

​Troubleshooting

​Common Installation Issues

​Getting Help

​Next Steps

Quickstart Tutorial

Project Structure

Development Workflow

Deployment

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Required Software

Operating System Support

Installation Steps

Configuration Overview

Vite Configuration

TypeScript Configuration

ESLint Configuration

Package Manager Comparison

Installing Alternative Package Managers

Environment Setup

Editor Configuration (VS Code)

Git Configuration

Building for Production

Troubleshooting

Common Installation Issues

Getting Help

Next Steps