🤖 Automated App-to-Library Conversion

🎯 Overview

This guide covers the automated tools and scripts for converting NX Angular applications to libraries. The automation handles file movement, configuration updates, and import path corrections automatically.

🚀 Conversion Script

Script Location and Usage

The conversion script is located at the workspace root:

# Make script executable (first time only)
chmod +x convert-app-to-lib.sh

# Usage syntax
./convert-app-to-lib.sh <app-name> <lib-name> <prefix>

# Examples
./convert-app-to-lib.sh singularity singularity-lib logic
./convert-app-to-lib.sh ux-test ux-test-lib ux
./convert-app-to-lib.sh editor-web editor-web-lib editor
./convert-app-to-lib.sh space-map space-map-lib space

Script Parameters

What the Script Does

1. Library Structure Creation

# Creates library if it doesn't exist
nx generate @nx/angular:library $LIB_NAME \
    --buildable=true \
    --routing=true \
    --standalone=true \
    --prefix=$PREFIX

2. File Movement (Git-Safe)

• Moves apps/{app-name}/src/app/* to libs/{lib-name}/src/lib/
• Uses git mv when possible to preserve history
• Removes auto-generated library files first

3. Configuration File Generation

ng-package.json

{
  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
  "dest": "../../dist/libs/{lib-name}",
  "lib": {
    "entryFile": "src/index.ts"
  }
}

src/index.ts (Library Entry Point)

/*
 * Public API Surface of {lib-name}
 */

// Export main routes
export * from './lib/{app-name}.routes';

// Export main layout component
export * from './lib/app.component';

// Add other exports as needed

project.json (Complete library configuration)

{
  "name": "{lib-name}",
  "projectType": "library",
  "prefix": "{prefix}",
  "targets": {
    "build": {
      "executor": "@nx/angular:ng-packagr-lite"
    }
  }
}

TypeScript Configurations

• tsconfig.lib.json - Development build config
• tsconfig.lib.prod.json - Production build config

4. Import Path Updates

# Automated import corrections
find libs/$LIB_NAME -name "*.ts" -exec sed -i.bak \
    -e 's|../../../libs/|@|g' \
    -e 's|../../libs/|@|g' \
    -e 's|../libs/|@|g' \
    -e 's|libs/|@|g' \
    {} \;

5. App-Specific File Cleanup

Removes these files:

• main.ts (app bootstrap)
• index.html (app entry point)
• polyfills.ts (app polyfills)
• styles.scss (global styles)

🔧 Manual Steps After Script

The script provides instructions for remaining manual steps:

1. Update tsconfig.base.json

{
  "compilerOptions": {
    "paths": {
      "@{lib-name}": ["libs/{lib-name}/src/index.ts"]
    }
  }
}

2. Create Routes File

// libs/{lib-name}/src/lib/{app-name}.routes.ts
import { Routes } from '@angular/router';

export const {AppName}Routes: Routes = [
  {
    path: '',
    loadComponent: () => import('./app.component').then(m => m.AppComponent),
    children: [
      // Define your routes here
    ]
  }
];

3. Update src/index.ts Exports

// Add specific exports based on your components
export * from './lib/components/dashboard/dashboard.component';
export * from './lib/services/my-service.service';
export * from './lib/models';

4. Test Build

nx build {lib-name}

5. Remove Old App (When Ready)

rm -rf apps/{app-name}

🎛️ Advanced Automation

Batch Conversion Script

Create a batch script for multiple apps:

#!/bin/bash
# batch-convert.sh

# Define apps to convert
declare -a apps=(
    "singularity:singularity-lib:logic"
    "ux-test:ux-test-lib:ux"
    "editor-web:editor-web-lib:editor"
    "space-map:space-map-lib:space"
)

# Convert each app
for app_config in "${apps[@]}"
do
    IFS=':' read -r app_name lib_name prefix <<< "$app_config"
    echo "Converting $app_name to $lib_name..."
    ./convert-app-to-lib.sh "$app_name" "$lib_name" "$prefix"
    echo "✅ $app_name converted to $lib_name"
    echo "---"
done

echo "🎉 Batch conversion complete!"
echo "Remember to:"
echo "1. Update tsconfig.base.json paths"
echo "2. Create routes files"
echo "3. Test all builds"

Post-Conversion Validation Script

#!/bin/bash
# validate-conversion.sh

LIB_NAME=$1

if [ -z "$LIB_NAME" ]; then
    echo "Usage: $0 <lib-name>"
    exit 1
fi

echo "🔍 Validating $LIB_NAME conversion..."

# Check required files exist
FILES=(
    "libs/$LIB_NAME/ng-package.json"
    "libs/$LIB_NAME/src/index.ts"
    "libs/$LIB_NAME/tsconfig.lib.json"
    "libs/$LIB_NAME/tsconfig.lib.prod.json"
    "libs/$LIB_NAME/project.json"
)

for file in "${FILES[@]}"; do
    if [ -f "$file" ]; then
        echo "✅ $file exists"
    else
        echo "❌ $file missing"
        exit 1
    fi
done

# Check app-specific files removed
APP_FILES=(
    "libs/$LIB_NAME/src/lib/main.ts"
    "libs/$LIB_NAME/src/lib/index.html"
    "libs/$LIB_NAME/src/lib/polyfills.ts"
)

for file in "${APP_FILES[@]}"; do
    if [ ! -f "$file" ]; then
        echo "✅ $file properly removed"
    else
        echo "⚠️  $file should be removed"
    fi
done

# Test build
echo "🔨 Testing build..."
if nx build "$LIB_NAME"; then
    echo "✅ Build successful"
else
    echo "❌ Build failed"
    exit 1
fi

echo "🎉 $LIB_NAME validation complete!"

🔍 Integration Automation

Main App Integration Helper

#!/bin/bash
# integrate-lib.sh

MAIN_APP=$1
LIB_NAME=$2
ROUTE_PATH=$3

if [ "$#" -ne 3 ]; then
    echo "Usage: $0 <main-app> <lib-name> <route-path>"
    echo "Example: $0 gograb-space singularity-lib singularity"
    exit 1
fi

echo "🔗 Integrating $LIB_NAME into $MAIN_APP..."

# Add to main app routes (this would need actual implementation)
echo "Manual step: Add to apps/$MAIN_APP/src/app/app.routes.ts:"
cat << EOF

{
  path: '$ROUTE_PATH',
  loadChildren: () => import('@$LIB_NAME').then(m => m.${LIB_NAME^}Routes),
  title: '${ROUTE_PATH^}'
}
EOF

echo "✅ Integration instructions provided"

📊 Automation Benefits

Time Savings

• Manual Process: 2-3 hours per app
• Automated Process: 5-10 minutes per app
• Error Reduction: 90% fewer manual mistakes

Consistency

• ✅ Standardized library structure
• ✅ Consistent naming conventions
• ✅ Proper configuration patterns
• ✅ Clean import paths

Safety

• ✅ Git history preservation
• ✅ Backup file creation
• ✅ Rollback capability
• ✅ Validation checks

🚨 Troubleshooting Automation

Script Permission Issues

# Fix permissions
chmod +x convert-app-to-lib.sh
chmod +x batch-convert.sh
chmod +x validate-conversion.sh

Git History Issues

# If git mv fails, script falls back to cp
# To preserve history manually:
git log --follow libs/my-lib/src/lib/component.ts

Import Path Issues

# If automated sed replacements miss some imports
# Manual fix using VS Code:
# 1. Find and Replace
# 2. Use regex: libs/([^/]+) 
# 3. Replace with: @$1

Build Failures

# Common fixes:
# 1. Missing exports in src/index.ts
# 2. Circular dependencies
# 3. Missing peer dependencies

# Debug build issues:
nx build my-lib --verbose

📋 Automation Checklist

Pre-Automation

• Git workspace is clean
• Script permissions set
• Target library names decided
• App dependencies documented

During Automation

• Run conversion script
• Monitor for errors
• Review generated files
• Check import path updates

Post-Automation

• Update tsconfig.base.json paths
• Create routes files
• Update src/index.ts exports
• Run validation script
• Test library builds
• Test integration

Final Verification

• All libraries build successfully
• Main app integrates properly
• All functionality preserved
• Documentation updated
• Team notified

📈 Performance Comparison

This automation dramatically reduces the effort and risk involved in converting applications to libraries, enabling large-scale architectural transformations with confidence.

🔗 Related Documentation

• App-to-Library Conversion Guide - Complete manual process
• Adding New Libraries - Creating libraries from scratch
• GoGrab Space Migration - Real-world migration example