AuroKit install and support improvements

[blackfalcon]

AuroKit Proposal

The Auro design system, composed of multiple npm packages, has posed challenges for developers due to the complexity of installation and version management. To streamline this process, AuroKit is proposed as an all-in-one npm package that consolidates essential Auro packages at pre-validated versions, ensuring compatibility and reducing development friction.

AuroKit aims to simplify the installation process, provides version stability, and allows for easier updates through npm update for patch updates automatically. It is recommended that AuroKit will be updated quarterly for new features and annually for major releases, aligning with Node.js version support to maintain modern compatibility.

By introducing AuroKit, developers can expect a more efficient, reliable development workflow, enhancing productivity and reducing potential integration issues. This strategic approach addresses feedback from developers, improves package management, and supports the long-term sustainability of the Auro ecosystem.

Problem Statement

The Auro design system consists of multiple npm packages that are each maintained at different versions. Developers have expressed that installing and managing these individual packages is complex and prone to version compatibility issues. This results in increased setup time and potential version conflicts that hinder development and integration.

Recommendation

To address these challenges, it is recommended to create AuroKit, a comprehensive npm package that aggregates all Auro design system packages. This solution will:

• Bundle the necessary Auro packages at versions that are validated for compatibility.
• Provide a streamlined installation process (npm install aurokit), ensuring a consistent and reliable development environment.
• Simplify version management by aligning all components to versions vetted by the Auro team.

Advantages of AuroKit

• Ease of Use: Developers can install one package (aurokit) rather than managing multiple individual dependencies.
• Compatibility Assurance: The versions included in AuroKit are verified to be compatible, reducing version conflicts and integration issues.
• Simplified Updates: Consumers can use npm update to apply minor and patch updates automatically, leveraging npm's built-in behavior to update packages based on their semver ranges.
• Improved Productivity: Developers save time by avoiding manual updates and version checks for individual packages.
• Quarterly Minor Releases: Ensures a predictable update cycle, providing a clear roadmap for new features without frequent disruptions.
• Annual Major Releases: Aligns with Node.js support updates, ensuring compatibility with the latest LTS versions and reducing the need for immediate, disruptive major updates.

Expectations

• Update Strategy:
  • AuroKit will only be updated quarterly for minor (feature) releases.
  • Major version updates will be scheduled annually, aligning with the Node.js support schedule.
  • Patch updates, while automatically included when running npm update, will require validation that they conform to minor or patch release standards.
• Release Cycle: The Auro team will evaluate and validate all new minor and patch releases for adherence to their scopes. Any update that significantly impacts compatibility or performance will undergo thorough review before integration into AuroKit.
• npm Update Feature Validation: It is confirmed that npm update automatically updates the minor and patch versions of packages as specified in the package.json dependencies' range.

Support

• Documentation: Comprehensive guides and release notes will be provided with each AuroKit update, highlighting included versions and any new features.
• Developer Support: The Auro team will provide support channels for questions and troubleshooting related to AuroKit usage.
• Monitoring and Feedback: The Auro team will gather ongoing feedback from developers to refine the update cycle and ensure AuroKit meets user needs.

Manage patch updates

Consumers of AuroKit, when performing npm update actions should be restricted to PATCH updates. This will reduce the number of localized errors due to potential incompatibility issues with MINOR release updates.

To restrict consumers to only PATCH updates, replace the caret ^ with a tilde ~ for each dependency.

"@aurodesignsystem/auro-accordion": "~3.1.13",

Direct dependency management

In a few cases there are direct dependencies defined within the scope of the component. There needs to be a review of this process to ensure that the proper versions are being defined and if this needs to be a direct dependency or should reside as a peer dependency.

It should be noted that defined peer dependencies are installed with the package automatically. It could be argued that unless there is a restriction on versions within the scope of a component, using peer dependencies will ensure that all components are relying on the same version of the dependency.

Peer dependency management

An issue when installing all Auro components in a single command is conflicts with peer dependencies. A common npm error devs will see is;

npm error While resolving: @aurodesignsystem/auro-[*]@0.0.0
npm error
npm error Could not resolve dependency:
npm error peer @aurodesignsystem/webcorestylesheets@"^5.1.2" from @aurodesignsystem/auro-button@8.2.0
npm error node_modules/@aurodesignsystem/auro-button
npm error   @aurodesignsystem/auro-button@"8.2.0" from the root project

It will be important to maintain peer dependency consistency across all Auro repos. One way to manage this is with the following BASH script. This series of functions will loop through a list of local directories, locate the ./package.json file and update /design-tokens and /webcorestylesheets dependencies. These are found to be the most common peer dependencies across all repos.

# This script is specifically designed to update the peer dependencies of the Auro components.
# It will iterate through the list of directories and update the peer dependencies of each component.

# Function to update package.json in a given directory
update_package_json() {
  local dir=$1
  local file_path="$dir/package.json"

  echo "Checking directory: $dir"

  # Check if package.json exists in the directory
  if [[ -f $file_path ]]; then
    echo "Found package.json in $dir"

    # Update @aurodesignsystem/design-tokens dependency
    if grep -q '"@aurodesignsystem/design-tokens": ' "$file_path"; then
      echo "Updating @aurodesignsystem/design-tokens in $file_path"
      sed -i.bak 's/"@aurodesignsystem\/design-tokens": "[^"]*"/"@aurodesignsystem\/design-tokens": "^4.10.1"/' "$file_path"
      echo -e "Updated @aurodesignsystem/design-tokens successfully."
    else
      echo "@aurodesignsystem/design-tokens not found in $file_path"
    fi

    # Update @aurodesignsystem/webcorestylesheets dependency
    if grep -q '"@aurodesignsystem/webcorestylesheets": ' "$file_path"; then
      echo "Updating @aurodesignsystem/webcorestylesheets in $file_path"
      sed -i.bak 's/"@aurodesignsystem\/webcorestylesheets": "[^"]*"/"@aurodesignsystem\/webcorestylesheets": "^6.0.0"/' "$file_path"
      echo -e "Updated @aurodesignsystem/webcorestylesheets successfully."

    else
      echo "@aurodesignsystem/webcorestylesheets not found in $file_path"
    fi
    sleep 1

    # Delete the backup file
    if [[ -f "$file_path.bak" ]]; then
      rm "$file_path.bak"
      echo "Deleted backup file: $file_path.bak"
    fi

  else
    echo "No package.json found in $dir"
  fi
}

# Function that iterates through directories and calls update_package_json
update_peerdeps() {
  local base_dir=$1

  if [[ -z $base_dir ]]; then
    echo "Please provide a directory name."
    return 1
  fi

  # Check if the provided directory exists
  if [[ -d $base_dir ]]; then
    update_package_json "$base_dir"
  else
    echo -e "Directory $base_dir not found.\n\n\n"
    return 1
  fi

  echo -e "Completed updates in $base_dir \n\n\n"
}

# Function to iterate over an array of directories and call update_peerdeps
function process_peerdeps() {
  # Array of directories
  local directories=(
  "accordion" "alert" "avatar" "background"
  "backtotop" "badge" "banner" "button"
  "card" "carousel" "checkbox" "combobox"
  "datepicker" "datetime" "dialog" "drawer"
  "dropdown" "flight" "flightline" "header"
  "hyperlink" "icon" "input" "loader"
  "lockup" "menu" "nav" "pane"
  "popover" "radio" "select" "sidenav"
  "skeleton" "table" "toast"
)

  # Loop through each directory and call the update_peerdeps function
  for dir in "${directories[@]}"; do
    update_peerdeps "$dir"
  done

  echo "All updates completed."
}

Conclusion

AuroKit represents a significant improvement in the usability, maintenance, and scalability of the Auro design system. By streamlining the process of dependency management and aligning releases with predictable cycles, AuroKit will enhance developer experience and maintain version stability across projects.

[blackfalcon]

A POC to support this proposal can be seen here https://github.com/AlaskaAirlines/AuroKit/tree/dsande/generalImprovements