Skip to main content

Installation & Setup

This guide will help you set up the AquaGen Web Application development environment from scratch.

Prerequisites​

Before you begin, ensure you have the following installed on your system:

Required Software​

SoftwareMinimum VersionRecommendedPurpose
Node.js18.0.020.x LTSJavaScript runtime
npm8.0.010.xPackage manager
Git2.30.0LatestVersion control

Optional Tools​

ToolPurpose
VS CodeRecommended IDE with extensions
Nx ConsoleVS Code extension for Nx commands
Firebase CLIFor deployment (install via: npm install -g firebase-tools)
Azure CLIFor Azure AD configuration

System Requirements​

  • Operating System: macOS, Linux, or Windows 10/11
  • RAM: Minimum 8GB (16GB recommended)
  • Disk Space: At least 5GB free space
  • Internet Connection: Required for package installation

Step 1: Verify Prerequisites​

Check your installed versions:

# Check Node.js version
node --version
# Should output: v18.x.x or higher

# Check npm version
npm --version
# Should output: 8.x.x or higher

# Check Git version
git --version
# Should output: git version 2.x.x or higher

If any tool is missing or outdated:

  • Node.js: Download from nodejs.org
  • npm: Comes with Node.js (or update via npm install -g npm@latest)
  • Git: Download from git-scm.com

Step 2: Clone the Repository​

Clone the AquaGen repository to your local machine:

# Navigate to your projects directory
cd ~/Documents/GitHub

# Clone the repository
git clone <repository-url> aquagen_web_appp

# Navigate into the project
cd aquagen_web_appp

Expected directory structure after cloning:

aquagen_web_appp/
├── apps/
├── libs/
├── docs/
├── package.json
├── nx.json
└── README.md

Step 3: Install Dependencies​

Install all required npm packages:

# Install all dependencies
npm install

What this does:

  • Installs all packages listed in package.json
  • Creates node_modules/ directory with ~1,300 packages
  • Generates package-lock.json for version locking
  • Sets up Nx workspace cache in .nx/

Expected output:

added 1347 packages, and audited 1348 packages in 2m
found 0 vulnerabilities

This may take 2-5 minutes depending on your internet speed.

Troubleshooting:

  • If you see permission errors, avoid using sudo. Fix npm permissions instead.
  • If installation fails, delete node_modules/ and package-lock.json, then retry.
  • For network issues, try: npm install --prefer-offline

Step 4: Environment Configuration​

4.1 Firebase Configuration​

If using Firebase for hosting, you'll need:

  1. Create a Firebase project at console.firebase.google.com

  2. Install Firebase CLI globally:

    npm install -g firebase-tools

  3. Login to Firebase:

    firebase login

  4. Initialize Firebase (if not already configured):

    firebase init hosting

  5. Update .firebaserc with your project ID:

    {
      "projects": {
        "default": "your-project-id"
      }
    }

4.2 Azure AD Configuration (for Authentication)​

The application uses Azure Active Directory for authentication:

  1. Register application in Azure AD:

    • Go to Azure Portal
    • Navigate to Azure Active Directory → App registrations
    • Create a new registration

  2. Configure redirect URIs:

    • Add http://localhost:4200 for development
    • Add your production URL for deployment

  3. Get credentials:

    • Copy Application (client) ID
    • Copy Directory (tenant) ID

  4. Update authentication configuration:

    • Configuration is typically in libs/shared/src/config/ or environment files
    • Set clientId, tenantId, and redirectUri

4.3 API Endpoints Configuration​

Update API endpoints in your configuration files:

// Example configuration location: libs/shared/src/config/api.config.js
export const API_CONFIG = {
  baseURL: 'https://your-api-endpoint.azurewebsites.net',
  timeout: 30000,
  // ... other settings
};

4.4 Environment Variables (Optional)​

Create environment-specific files if needed:

# Create .env file (if required)
touch .env.local

# Example contents:
# REACT_APP_API_URL=https://api.example.com
# REACT_APP_AZURE_CLIENT_ID=your-client-id
# REACT_APP_AZURE_TENANT_ID=your-tenant-id

Note: Environment variables should be prefixed with REACT_APP_ to be accessible in the application.

Step 5: Verify Installation​

5.1 Check Nx Installation​

# Verify Nx is working
npx nx --version
# Should output: 21.2.1

5.2 View Project Graph​

# Open Nx project graph (visual representation of dependencies)
npx nx graph

This opens a browser showing your app and library dependencies.

5.3 List All Projects​

# List all apps and libraries
npx nx show projects

Expected output:

production
demo
production-e2e
demo-e2e
alerts
aquagpt
components
dashboard
energy
monitoring
... (25+ libraries)

Step 6: Start Development Server​

Start the application in development mode:

# Start the production app
npm start

Or explicitly:

npm run start

What this does:

  • Starts Rspack dev server on http://localhost:4200
  • Enables hot module reloading (HMR)
  • Compiles TypeScript and JSX
  • Serves application with security headers

Expected output:

> nx run production:serve

✔ Build succeeded
  ➜  Local:   http://localhost:4200/
  ➜  Network: use --host to expose

Access the Application​

Open your browser and navigate to:

http://localhost:4200

You should see the AquaGen splash screen or login page.

Step 7: Verify Build Process​

Test that the production build works:

# Build the production app
npm run build

Expected output:

> nx run production:build

✔ Build succeeded

Output will be written to: dist/apps/production

Build artifacts location:

dist/
└── apps/
    └── production/
        ├── index.html
        ├── main.*.js
        ├── styles.*.css
        └── assets/

Additional Setup (Optional)​

Install Nx Console (VS Code)​

  1. Open VS Code
  2. Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
  3. Search for "Nx Console"
  4. Click Install

Benefits:

  • Visual interface for running Nx commands
  • Project graph visualization
  • Generate code with forms
  • Task running shortcuts

Configure ESLint & Prettier (VS Code)​

Install recommended extensions:

  • ESLint: For code linting
  • Prettier: For code formatting

Add to VS Code settings (.vscode/settings.json):

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

Install React Developer Tools​

Browser extensions for React debugging:

Common Issues & Solutions​

Issue: "Module not found" errors​

Solution:

# Clear Nx cache
npx nx reset

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Issue: Port 4200 already in use​

Solution:

# Find and kill process using port 4200
lsof -ti:4200 | xargs kill -9

# Or start on a different port
npx nx serve production --port=4300

Issue: Build fails with memory errors​

Solution:

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=8192"
npm run build

Issue: Git clone fails with SSL errors​

Solution:

# Temporarily disable SSL verification (use with caution)
git config --global http.sslVerify false

# Clone the repository
git clone <repository-url>

# Re-enable SSL verification
git config --global http.sslVerify true

Next Steps​

Now that your environment is set up:

  1. Explore the codebase: Start with Project Structure
  2. Understand the architecture: Read Micro-Frontend Architecture
  3. Start developing: Follow Development Workflow
  4. Learn the commands: Check Commands Reference

Quick Reference​

Essential commands:

# Install dependencies
npm install

# Start development server
npm start

# Build for production
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Open project graph
npx nx graph

Installation Complete! You're ready to start developing with AquaGen.

For help, see Troubleshooting or FAQ.