Getting Started with MIJUG .NET Workspace

Welcome to the comprehensive setup guide for the MIJUG .NET workspace - a powerful development environment that combines TypeScript application development with Jekyll documentation, all optimized for WSL integration.

📋 Prerequisites: This guide assumes you have the main repository access. For public users, the core concepts and architecture are documented here, but specific installation commands are available in the private repository.

Getting Started with MIJUG .NET Workspace

Quick Setup Overview

Essential Commands

# 1. Install dependencies
npm install
cd docs && bundle install && cd ..

# 2. Start development (process-safe)
npm run dev:safe            # Checks for conflicts first
npm run quick:start         # Fast startup with process checking

# 3. Build for production (process-safe)
npm run quick:build         # Build with process checking
npm run build:parallel:safe # Parallel build with safety checks

# 2. Start development environment
npm run dev:optimized          # Parallel TypeScript + Jekyll development

# 3. Verify setup
npm run health-check          # Comprehensive environment validation

Technology Stack

TypeScript 5.5+ with ES2022 target and strict compilation
Jekyll 4.4.1 with Ruby 3.3.8+YJIT for enhanced performance
Node.js 22.8+ LTS with nvm management
WSL2 + Ubuntu 24.04 LTS for cross-platform development

Core Architecture

Workspace Structure

mijug-dot-net-project/          # Development workspace
├── src/                        # TypeScript source code
├── docs/                       # Jekyll documentation site
├── tests/                      # Jest unit tests
├── e2e/                        # Playwright E2E tests
├── scripts/                    # Build and deployment automation
└── package.json               # 70+ npm commands for all workflows

mijug-dot-net/                  # Auto-generated public repository
└── docs/                       # Deployed Jekyll site

Development Philosophy

Dual Repository Workflow: Private development → Public deployment
Performance First: < 12s builds, < 90s test suite, memory-optimized
Quality Gates: ESLint, Prettier, accessibility, cross-browser testing
Developer Experience: Hot reload, parallel builds, intelligent caching

Development Workflows

🚀 Quick Start Development

# Ultra-fast startup (< 15 seconds)
npm run quick:start             # TypeScript + Jekyll with drafts + monitoring
npm run dev:fast               # Skip initial build for rapid iteration

# Comprehensive development
npm run dev:optimized          # Memory-efficient parallel development

🧪 Testing Workflows

# Quick validation (< 15 seconds)
npm run test:smoke             # Unit + Chromium E2E

# Comprehensive testing (< 90 seconds)
npm run test:all:safe          # Jest + Playwright + Accessibility + Mermaid

# Specialized testing
npm run test:a11y              # WCAG 2.1 AA compliance testing
npm run test:browser-compat    # Multi-browser compatibility matrix

🏗️ Build & Deployment

# Development builds
npm run build:parallel         # TypeScript + Jekyll simultaneously
npm run build:fast             # Rapid iteration builds

# Production builds
npm run build:parallel:optimized # Memory-efficient production builds
npm run deploy:optimized       # Automated private → public sync

# Pre-commit validation
npm run precheckin             # Format → lint → clean → build → test → validate

Key Features & Capabilities

TypeScript Development

Full IntelliSense Support: Autocomplete, type checking, and refactoring
Modern ES Features: ES2022 target with latest JavaScript features
Debugging Integration: VS Code debugging with source maps
Build Optimization: Parallel compilation with memory limits

Jekyll Documentation

Live Reload: Instant feedback with automatic rebuilds and browser refresh
Advanced Markdown: Enhanced syntax with code highlighting and tables
SEO Optimized: Built-in SEO tags, sitemap generation, and meta optimization
Content Management: FrontMatter CMS integration for visual editing

Testing Excellence

Multi-Level Testing: Jest unit tests, Playwright E2E, accessibility compliance
Cross-Browser Matrix: Automated testing across Chromium, Firefox, WebKit
Performance Monitoring: Built-in performance analysis and optimization
CI/CD Integration: GitHub Actions with parallel job execution

Quality Assurance

Code Standards: ESLint 9.15.0 with flat config, Prettier formatting
Accessibility: WCAG 2.1 AA compliance with axe-core integration
Security: SBOM generation, vulnerability scanning, dependency auditing
Performance: Memory optimization, cache management, build monitoring

Development Environment Setup

Node.js & TypeScript

# Verify Node.js version (22.8+ LTS required)
node --version
npm --version

# TypeScript compilation check
npx tsc --noEmit                # Type checking without output
npm run build:ts               # Full TypeScript build

Ruby & Jekyll

# Verify Ruby version (3.3.8+ required)
ruby --version
bundle --version

# Jekyll development
cd docs
bundle exec jekyll serve --livereload --drafts  # Development server
bundle exec jekyll build                        # Production build

Code Examples

TypeScript Function with Types

export interface WorkspaceConfig {
  name: string;
  version: string;
  features: string[];
}

export function createWorkspace(config: WorkspaceConfig): Promise<boolean> {
  console.log(`Setting up ${config.name} v${config.version}`);
  return Promise.resolve(true);
}

// Usage
const config: WorkspaceConfig = {
  name: "MIJUG .NET Workspace",
  version: "1.3.5",
  features: ["TypeScript", "Jekyll", "Testing", "CI/CD"],
};

createWorkspace(config).then((success) => {
  console.log("Workspace ready:", success);
});

Jekyll Front Matter Configuration

---
layout: post
title: "Development Guide"
date: 2025-09-08
categories: [development, tutorial]
tags: [typescript, jekyll, testing]
nav_order: 2
description: "Complete development environment setup"
author: "MIJUG Team"
---

Package.json Script Examples

{
  "scripts": {
    "dev:optimized": "concurrently \"npm run dev:ts\" \"npm run dev:jekyll\" --names \"TS,Jekyll\"",
    "test:all:safe": "npm run test:unit && npm run test:e2e && npm run test:a11y",
    "build:parallel": "concurrently \"npm run build:ts\" \"npm run build:jekyll\"",
    "precheckin": "npm run format && npm run lint:fix && npm run clean && npm run build:all && npm run test:all"
  }
}

Troubleshooting

Common Setup Issues

Node.js Version Problems

Problem: TypeScript compilation fails or npm scripts error
Solution:

# Use Node Version Manager
nvm install --lts
nvm use --lts
nvm alias default node

Ruby/Jekyll Issues

Problem: Bundle install fails or Jekyll won’t start
Solution:

# Configure Ruby environment
echo 'export GEM_HOME=$HOME/gems' >> ~/.bashrc
echo 'export PATH=$HOME/gems/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Reinstall dependencies
cd docs
bundle clean --force
bundle install

Permission Errors

Problem: Cannot write to directories or install packages
Solution:

# Fix npm permissions (avoid sudo)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# Fix Ruby gem permissions
gem install bundler --user-install

Port Conflicts

Problem: Development servers conflict on ports 4000 or 3000
Solution:

# NEW: Use automated process checking (recommended)
npm run check-processes    # Check for conflicts
npm run kill-dev-servers   # Kill conflicting processes
npm run dev:restart        # Clean restart

# Manual approach (if needed)
lsof -i :4000
lsof -i :3000
kill -9 <PID>

# Use alternative ports
npm run dev:jekyll -- --port 4001

Build Cache Corruption

Problem: Builds fail or produce inconsistent results
Solution:

# Use process-safe build commands (recommended)
npm run build:parallel:safe    # Build with process checking
npm run quick:build            # Quick build with safety checks

# Manual cleanup
npm run kill-dev-servers && npm run clean && npm run build

WSL File System Issues

Problem: File watching doesn’t work or builds are slow
Solution:

# Increase file watchers limit
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# Use WSL2 file system (not Windows mount)
# Work in /home/user/ not /mnt/c/

Performance Optimization

Memory Issues

# Increase Node.js memory limit
npm run build:ts -- --max-old-space-size=4096

# Use memory-efficient testing
npm run test:memory-efficient

Build Speed

# Use parallel builds
npm run build:parallel:optimized

# Enable caching
npm run cache:optimize

Next Steps

Once your environment is set up, explore these guides in order:

Workspace Overview - Understand the complete architecture
FrontMatter CMS - Visual content management setup
Accessibility Testing - WCAG compliance configuration
Browser Compatibility Testing - Cross-browser testing setup
Performance Optimization - Advanced optimization techniques

Performance Targets

Operation	Target Time	Command
Development Startup	< 15s	`npm run quick:start`
Parallel Build	< 12s	`npm run build:parallel:optimized`
Smoke Tests	< 15s	`npm run test:smoke`
Full Test Suite	< 90s	`npm run test:all:safe`
Pre-commit Check	< 120s	`npm run precheckin`

Getting Help

Environment Issues: Run npm run health-check for diagnostics
Specific Topics: Explore the complete documentation
Community Support: Contact our team for assistance
GitHub Issues: Check the repository for known issues and solutions

Environment: WSL2 + Ubuntu 24.04 LTS | Node.js v22.8+ | Ruby v3.3.8+YJIT
Last Updated: September 8, 2025