Simplifying Package Scope Migration: Introducing the Scope Migrator Tool
In the ever-evolving landscape of JavaScript development, managing package dependencies effectively is crucial. Today, we’re excited to introduce the Scope Migrator Tool - a powerful command-line utility designed to streamline the process of migrating packages from the @amzn/ scope to @amazon-devices/ scope in JavaScript and TypeScript projects.
Why This Migration?
Amazon is moving Vega libraries from our private npm registry to the public registry. This transition requires changing our package namespace from @amzn to @amazon-devices. The shift brings three benefits:
- Simplified Development: Developers will no longer need to configure
.npmrctokens for Kepler development. - Improved Library Accessibility: Our SDK will be more easily accessible through the public registry.
- Streamlined namespaces: While there will be a temporary period of dual use of namespaces, we plan to sunset
@amznfor external use
This change affects both current users of our SDK and our library integration partners. While existing applications will continue to function without immediate changes, we’re providing tools and support to make the eventual migration as smooth as possible.
Enter the Scope Migrator Tool
Recognizing the potential complexity of this transition, especially for large projects or those with deep integrations, we’ve developed the Scope Migrator Tool. This utility is designed to automate the process of updating package references across your entire codebase, minimizing the manual effort required and reducing the risk of errors during migration.
What Does It Do?
The Scope Migrator Tool automates the tedious and error-prone process of updating package scope references across your entire project. It intelligently scans your codebase, identifying and replacing all occurrences of @amzn/ with @amazon-devices/ in various file types while maintaining your project’s integrity.
Key Features
- Safety-First Approach: Runs in dry-run mode by default to prevent unintended changes
- Comprehensive Coverage: Supports multiple file types including JS, TS, JSON, and more
- Monorepo Support: Seamlessly handles complex project structures
- Smart Exclusions: Automatically skips build directories and dependencies
- NPM Registry Migration: Handles registry configuration updates automatically
Overview
This tool automatically scans a project directory and replaces all occurrences of @amzn/ with @amazon-devices/ in supported file types. It operates in dry-run mode by default to ensure safety and is designed for both single projects and monorepo structures.
Getting Started
Download it
Please download the script here:
scope_migrator.py (92.5 KB)
Basic Usage
To start with a safe preview of changes, simply run:
python scope_migrator.py
This will scan your current directory and show you what would be changed without actually making any modifications.
Making Real Changes
When you’re ready to perform the actual migration:
python scope_migrator.py --no-dry-run
Working with Specific Directories
To target a specific project directory:
python scope_migrator.py --project-root /path/to/your/project
Advanced Configuration
The tool offers various customization options to handle specific project needs:
Custom Exclusions
# Exclude specific paths
python scope_migrator.py --exclude-paths "src/legacy/" "docs/archive/"
# Exclude folder names at any depth
python scope_migrator.py --exclude-folders "temp" "cache"
# Exclude specific files
python scope_migrator.py --exclude-files "custom-config.json"
Command Line Options
| Option | Description |
|---|---|
--project-root DIR |
Root directory of the project to process (default: current directory) |
--no-dry-run |
Make actual changes instead of just previewing (default: dry-run only) |
--exclude-paths PATH [PATH ...] |
Additional paths to exclude from processing |
--exclude-folders FOLDER [FOLDER ...] |
Additional folder names to exclude at any depth |
--exclude-files FILE [FILE ...] |
Additional files to exclude from processing |
--help |
Show help message and exit |
Automatically Excluded
The following are automatically excluded from processing:
Directories (at any depth - monorepo support):
-
build/- Build output directories -
node_modules/- NPM dependencies
Directories (at root level only):
-
.git/- Git repository data -
dist/- Common build output directory
Files:
package-lock.json- NPM lock file (auto-generated)
Requirements
-
Python 3.6 or higher
-
No external dependencies (uses only Python standard library)
Best Practices
-
Always run a dry-run first to see what would be changed
-
Review the output to ensure only expected files are being modified
-
Backup your code before running with
--no-dry-run(or use version control) -
Test your application after migration to ensure everything works correctly
Frequently Asked Questions
Q: Is it safe to use in production projects?
A: Yes! The tool’s default dry-run mode ensures you can preview all changes before applying them. Additionally, it automatically creates backups of important configuration files.
Q: What file types are supported?
A: The tool supports a wide range of file types including JavaScript, TypeScript, JSON, Markdown, HTML, CSS, YAML, and more.
Q: Will it affect my node_modules directory?
A: No, the tool automatically excludes node_modules and other build-related directories to ensure safety.
Q: Does it work with monorepos?
A: Yes, the tool is designed to handle complex project structures including monorepos.
Q: When should I use this script?
A: The script is intended to accelerate your migration from @amzn to @amazon-devices , so typically you would use this script to do your initial migration. If your application relies on 3rd party service libraries that have not yet migrated to @amazon-devices, you may need to re-run the script again after updating those libraries.
Q: Do I need the script? Can I do it myself using AI and/or find replace?
A: The script is optional, so you can do it yourself. We recommend at least running the script in “dry run” mode (default) to double check if you may have missed anything. Some 3rd party service libraries (analytics, ad insertion, etc) may bring in transitive dependencies on @amzn and this script will help identify and address those in addition to your main application source code.
Q: Why is this script so long?
A: We wanted to make this script 1) independent, so that it didn’t rely on anything beyond the Python standard library to simplify installation and usage on different systems; 2) compatible with multiple dependency managers (npm, pnmpm, yarn).
Troubleshooting
No files found to process
-
Check that you’re in the correct directory or specify the right
--project-root -
Ensure your files have supported extensions
-
Check if files are being excluded by the default exclusion rules
Permission errors
-
Ensure you have write permissions to the files and directories
-
On Unix systems, you may need to run with appropriate permissions
Unexpected files being modified
-
Use the dry-run mode first to preview changes
-
Add specific exclusions using
--exclude-paths,--exclude-foldersor--exclude-files
Have questions or need support? Contact our support team through the designated support channels or reach out to your Partner Solutions Architect.