Hua.Abp.Demo/angular/scripts/README.md

Symlink Management Scripts

This directory contains PowerShell scripts for managing symbolic links between package directories in the Lepton project. These scripts help optimize development workflow by creating symlinks to shared dependencies instead of duplicating them across multiple package directories.

You will need to run these scripts if you need to reference an installed package on the main angular application.

📁 Files Overview

File	Purpose	Description
symlink-config.ps1	Configuration	Shared configuration file defining package directories and packages to symlink
setup-symlinks.ps1	Setup	Creates selective symlinks for specific packages across library directories
remove-symlinks.ps1	Cleanup	Removes all symlinked node_modules directories

🚀 Quick Start

Prerequisites

1. PowerShell: Ensure you have PowerShell Core (pwsh) installed
2. Dependencies: Run yarn install in the main demo app directory first (Demo/angular)
3. Permissions: On Windows, you may need to run PowerShell as Administrator for symlink creation

Basic Usage

# Navigate to the scripts directory
cd Demo/angular/scripts

# Setup symlinks (run this first)
./setup-symlinks.ps1

# Remove symlinks when done
./remove-symlinks.ps1

📋 Detailed Script Documentation

🔧 symlink-config.ps1

Purpose: Centralized configuration for all symlink operations.

Configuration:

• Package Directories: Defines all library directories that need symlink management
• Packages to Symlink: Lists specific npm packages that should be symlinked

Key Variables:

• $script:PackageDirectories: Array of relative paths to library directories
• $script:PackagesToSymlink: Array of package names to symlink

Functions:

• Get-PackageDirectories(): Returns the list of package directories
• Get-PackagesToSymlink(): Returns the list of packages to symlink

🔗 setup-symlinks.ps1

Purpose: Creates selective symlinks for shared dependencies across library directories.

What it does:

1. Reads configuration from symlink-config.ps1
2. Identifies the main app's node_modules directory
3. For each library directory:
   • Creates a node_modules directory if it doesn't exist
   • Creates symlinks for each configured package
   • Skips packages that don't exist in the main node_modules
   • Avoids circular symlinks

Example Output:

🔗 Setting up selective symlinks for specific packages...

📦 Packages to symlink:
   • @angular
   • @abp
   • @volo
   • @volosoft
   • @ngx-validate
   • @swimlane
   • rxjs
   • cropperjs
   • angularx-qrcode
   • qrcode

📁 Processing ./../modules/Volo.Abp.Identity.Pro/angular/projects/account..
   ✅ Linked @angular
   ✅ Linked @abp
   ✅ Linked @volo
   ...

🎉 Symlinks completed! Linked: 45, Skipped: 3

🗑️ remove-symlinks.ps1

Purpose: Removes all symlinked node_modules directories to clean up the workspace.

What it does:

1. Reads configuration from symlink-config.ps1
2. For each library directory:
   • Locates the node_modules directory
   • Removes the entire directory (which contains symlinks)
   • Reports success/failure for each operation

Example Output:

🗑️  Removing symlinks from library directories...

📁 Processing ../../modules/Volo.Abp.Identity.Pro/angular/projects/account...
   ✅ Removed node_modules directory

📁 Processing ./../modules/Volo.Abp.Identity.Pro/angular/projects/account...
   ✅ Removed node_modules directory

🎉 Cleanup completed! Removed: 8, Skipped: 0
💡 Libraries will now use their own local dependencies (if any)

⚙️ Configuration

Adding New Package Directories

Edit symlink-config.ps1 and add new paths to the $script:PackageDirectories array:

$script:PackageDirectories = @(
   "./../modules/Volo.Abp.Identity.Pro/angular"
    # Add your new directory here
)

Adding New Packages to Symlink

Edit symlink-config.ps1 and add package names to the $script:PackagesToSymlink array:

$script:PackagesToSymlink = @(
    "@angular",
    "@abp",
    # Add your new package here
    "your-new-package"
)

🚨 Troubleshooting

Common Issues

Error: "Export-ModuleMember can only be called from inside a module"

• ✅ Fixed: This was resolved by removing the Export-ModuleMember line from symlink-config.ps1

Error: "Main app node_modules not found"

• Solution: Run yarn install in the main demo app directory first

Error: "Access denied" on Windows

• Solution: Run PowerShell as Administrator

Symlinks not working on Windows

• Solution: Enable Developer Mode in Windows Settings, or run as Administrator

Platform-Specific Notes

Windows:

• Uses cmd /c "mklink /J" for directory junctions
• May require Administrator privileges
• Consider enabling Developer Mode for easier symlink creation

macOS/Linux:

• Uses New-Item -ItemType SymbolicLink
• Generally works without special permissions
• May require ln -s if PowerShell symlinks don't work

📝 Notes

• These scripts are designed for development environments
• Always run remove-symlinks.ps1 before committing changes
• The scripts use relative paths, so they must be run from the scripts directory
• Symlinks are automatically detected and handled by most development tools
• Consider adding symlinked directories to .gitignore if needed

🤝 Contributing

When modifying these scripts:

1. Test on both Windows and macOS/Linux
2. Update this README if you change functionality
3. Ensure error handling is robust
4. Maintain backward compatibility with existing configurations