How to Set Up Angular CLI with Server Side Rendering on macOS 2025

Server-side rendering (SSR) in Angular significantly improves initial page load performance and SEO for your web applications. However, setting up Angular CLI with SSR on macOS involves multiple configuration steps that often trip up developers unfamiliar with the process.

This guide walks you through the complete setup process, from initial prerequisites through running your first SSR-enabled Angular application on macOS.

Prerequisites for Angular SSR on macOS

Before you begin, ensure your macOS system has the following installed:

Required Software:

• Node.js 18.x or higher (includes npm)
• Xcode Command Line Tools
• A code editor (VS Code recommended)

Verify your versions in Terminal:

node --version
npm --version
xcode-select --version

If you don't have Xcode Command Line Tools installed, run:

xcode-select --install

Step-by-Step Angular CLI Setup with SSR

1. Install Angular CLI Globally

Open Terminal and install the latest Angular CLI:

npm install -g @angular/cli

Verify installation:

ng version

You should see Angular CLI version 17.0.0 or higher for optimal SSR support.

2. Create a New Angular Workspace

Generate a new Angular project with SSR enabled from the start:

ng new my-ssr-app --ssr
cd my-ssr-app

The --ssr flag automatically configures all necessary SSR dependencies and files during project creation.

3. Verify SSR Configuration Files

Check that your project contains these critical SSR configuration files:

• src/main.server.ts - Server bootstrap file
• server.ts - Express server configuration
• angular.json - Updated with server build configuration
• tsconfig.server.json - Server-specific TypeScript configuration

If you're adding SSR to an existing Angular project, run:

ng add @angular/ssr

4. Install Dependencies

Ensure all packages are properly installed:

npm install

On M1/M2 Macs, you may encounter compatibility issues. If installation fails, try:

npm install --legacy-peer-deps

5. Build the Application

Build both the client and server bundles:

ng build

This creates:

• Client build in dist/my-ssr-app/browser/
• Server build in dist/my-ssr-app/server/

Running Your Angular SSR Application

Development Mode

For local development with hot reloading:

ng serve

The application will run on http://localhost:4200 with SSR enabled during development.

Production Mode

For production builds:

npm run build
npm run serve:ssr

This starts your Express server on http://localhost:4000, serving your application with server-side rendering.

Common Configuration Issues on macOS

Issue 1: Port Already in Use

If port 4200 or 4000 is occupied:

# Find the process using the port
lsof -i :4200

# Kill the process
kill -9 <PID>

# Or specify a different port
ng serve --port 4300

Issue 2: Module Not Found Errors

If you encounter Cannot find module '@angular/ssr':

rm -rf node_modules package-lock.json
npm install

Issue 3: TypeScript Compilation Errors

Ensure your tsconfig.server.json extends the base configuration:

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./out-tsc/server"
  },
  "files": [
    "src/main.server.ts"
  ]
}

Performance Verification

After setup, verify SSR is working correctly:

curl -I http://localhost:4000

Look for the rendered HTML in the response body (not just a script tag). The initial HTML payload should contain your Angular application's DOM structure.

Environment-Specific Configuration

Create environment-specific configurations for macOS development:

// src/environments/environment.server.ts
export const environment = {
  production: false,
  apiUrl: 'http://localhost:3000',
  ssr: true
};

Key Considerations for macOS Development

| Factor | macOS Consideration | |--------|---------------------| | Node Version | Use nvm to manage multiple versions; set to 18+ for SSR | | File Permissions | Ensure execute permissions on npm global bin directory | | Memory | M1/M2 Macs may require increased Node heap size for large builds | | Path Issues | Use absolute paths in environment configs to avoid relative path problems |

Next Steps After Setup

1. Implement Transfer State: Use Angular's TransferState to avoid double HTTP requests between server and client
2. Configure Caching: Set appropriate cache headers in your Express server
3. Monitor Performance: Use Chrome DevTools to verify initial page load improvements
4. Deploy to Production: Consider platforms like Vercel, Netlify, or DigitalOcean App Platform that natively support Angular SSR applications

Troubleshooting Commands

Keep these commands handy for debugging:

# Clear Angular cache
ng cache clean

# Rebuild with verbose output
ng build --verbose

# Run development server with verbose logging
ng serve --verbose

# Check all installed global Angular packages
npm list -g @angular

Setting up Angular CLI with SSR on macOS requires attention to several configuration points, but following this guide ensures a smooth development environment. The performance improvements gained from server-side rendering—particularly for SEO and initial page load times—make the setup effort worthwhile for production Angular applications.