VTEX CLI Plugin - Redirects

🚀 High-performance redirect management for VTEX IO

A powerful VTEX CLI plugin for managing URL redirects in your VTEX account and workspace. Features optimized CSV operations, parallel processing, and memory-efficient file handling for large datasets.

✨ Features

• Export all redirects to CSV with streaming optimization
• Import redirects from CSV files with batch processing
• Delete redirects using CSV file input
• Memory efficient - handles large datasets without OOM issues
• Parallel processing - configurable concurrency for optimal performance
• Resume support - automatically recovers from interruptions
• Progress tracking - real-time progress indicators

📦 Installation

Install the Plugin

# Install the plugin to your VTEX CLI
vtex plugins install @vtex/cli-plugin-redirects

Development Setup

For development or local testing:

# Clone the repository
git clone https://github.com/vtex/cli-plugin-redirects.git
cd cli-plugin-redirects

# Install dependencies
yarn install

# Build the plugin
yarn build

# Link for local development
vtex plugins link

🚀 Commands

vtex redirects export [CSV_FILE]

Exports all redirects from the current account and workspace to a CSV file.

Features:

• Memory-efficient streaming export
• Handles millions of redirects without OOM
• Configurable concurrency and batch processing
• Automatic resume on interruption

# Basic export
vtex redirects export my-redirects.csv

# With performance tuning
EXPORT_CONCURRENCY=10 EXPORT_BATCH_SIZE=200 vtex redirects export large-export.csv

CSV Format:

from,to,type,endDate,binding
/old-page,/new-page,PERMANENT,,
/temporary,/temp-new,TEMPORARY,2024-12-31,

Environment Variables:

• EXPORT_CONCURRENCY - Number of parallel processors (default: 5)
• EXPORT_BATCH_SIZE - CSV rows per write batch (default: 100)

vtex redirects import [CSV_FILE]

Imports redirects from a CSV file to the current account and workspace.

# Import redirects
vtex redirects import my-redirects.csv

# Import with reset (removes all existing redirects first)
vtex redirects import my-redirects.csv --reset

Options:

• -r, --reset - Remove all existing redirects before importing
• -v, --verbose - Show debug level logs
• --trace - Trace all requests to VTEX IO

vtex redirects delete [CSV_FILE]

Deletes redirects using paths specified in a CSV file.

# Delete specific redirects
vtex redirects delete redirects-to-delete.csv

CSV Format for deletion:

from
/page-to-remove
/another-old-page

🔧 Performance Configuration

Optimizing Export Performance

For large datasets, tune these environment variables:

# High-performance setup for large exports
export EXPORT_CONCURRENCY=10      # More parallel processors
export EXPORT_BATCH_SIZE=500      # Larger write batches

# Memory-constrained setup
export EXPORT_CONCURRENCY=3       # Fewer parallel processors
export EXPORT_BATCH_SIZE=50       # Smaller write batches

Memory Usage Guidelines

| Dataset Size | Concurrency | Batch Size | Memory Usage | | ------------------- | ----------- | ------------- | ------------ | | < 100K redirects | 5 (default) | 100 (default) | ~50MB | | 100K - 1M redirects | 8 | 200 | ~100MB | | > 1M redirects | 10 | 500 | ~200MB |

📋 CSV File Format

Export Format

The export command generates CSV files with these columns:

| Column | Description | Example | | --------- | -------------------------- | -------------------------- | | from | Source URL path | /old-product | | to | Target URL path | /new-product | | type | Redirect type | PERMANENT or TEMPORARY | | endDate | Expiration date (optional) | 2024-12-31 | | binding | Store binding (optional) | store-1 |

Import Requirements

• CSV files must include at minimum: from, to columns
• type defaults to PERMANENT if not specified
• Encoding should be UTF-8
• Maximum file size: No limit (streams processing)

🛠️ Development

Setup

# Clone and setup
git clone https://github.com/vtex/cli-plugin-redirects.git
cd cli-plugin-redirects
yarn install

# Development workflow
yarn watch          # Auto-rebuild on changes
yarn test           # Run tests
yarn lint           # Check code style
yarn build          # Production build

Testing

# Run all tests
yarn test

# Run with coverage
yarn test --coverage

# Test specific command
vtex redirects export test-export.csv --verbose

🐛 Troubleshooting

Common Issues

Out of Memory Errors

# Reduce concurrency and batch size
export EXPORT_CONCURRENCY=3
export EXPORT_BATCH_SIZE=50

Network Timeouts

# Use verbose mode to see detailed logs
vtex redirects export file.csv --verbose

CSV Format Errors

• Ensure CSV has required columns (from, to)
• Check for proper UTF-8 encoding
• Validate no empty required fields

Debug Mode

Enable verbose logging for detailed information:

vtex redirects export file.csv --verbose --trace

📊 Performance Benchmarks

| Operation | Dataset Size | Time | Memory | | --------- | -------------- | ------- | ------ | | Export | 100K redirects | ~2 min | ~50MB | | Export | 1M redirects | ~15 min | ~100MB | | Import | 100K redirects | ~5 min | ~30MB | | Delete | 10K redirects | ~30 sec | ~20MB |

Benchmarks measured on standard cloud infrastructure

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

This project uses:

• ESLint for code linting
• Prettier for code formatting
• TypeScript for type safety

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• VTEX Help: VTEX Help Center
• Developer Docs: VTEX IO Documentation

Made with ❤️ by the VTEX team