|
| 1 | +# Contentstack CLI Migration Guide: 1.x.x to 2.x.x-beta |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +This guide helps you migrate from Contentstack CLI 1.x.x to the new 2.x.x-beta version. The new version introduces significant improvements in performance, user experience, and functionality. |
| 6 | + |
| 7 | +## Major Changes |
| 8 | + |
| 9 | +### 1. 🚀 TypeScript Module Support (Default) |
| 10 | + |
| 11 | +**What Changed:** |
| 12 | +- Removed `export-info.json` support |
| 13 | +- TypeScript modules are now the default for export and import operations |
| 14 | +- Improved performance and reliability |
| 15 | + |
| 16 | +**Before (1.x.x):** |
| 17 | +```bash |
| 18 | +csdx cm:stacks:export -d "./export-data" -k bltxxxxxx |
| 19 | +``` |
| 20 | +The CLI generated an export-info.json file containing a contentVersion field: |
| 21 | +contentVersion: 2 for TypeScript modules |
| 22 | +contentVersion: 1 for JavaScript modules (default) |
| 23 | +This version indicator helped the import process select the appropriate module structure, as TypeScript and JavaScript modules have different structures for assets, entries, and other components. |
| 24 | + |
| 25 | +**After (2.x.x-beta):** |
| 26 | +```bash |
| 27 | +csdx cm:stacks:export -d "./export-data" -k bltxxxxxx |
| 28 | +``` |
| 29 | +No export-info.json file is generated |
| 30 | +TypeScript modules are used by default for all operations |
| 31 | +Simplified export structure with consistent module formatting |
| 32 | + |
| 33 | +**Migration Action:** Remove `export-info.json` file generation logic from export plugin. |
| 34 | + |
| 35 | +### 2. 🌿 Main Branch Export (Default) |
| 36 | + |
| 37 | +**What Changed:** |
| 38 | +- By default, only the main branch content is exported |
| 39 | +- Consistent behavior with import operations |
| 40 | +- Faster exports for most use cases |
| 41 | + |
| 42 | +**Before (1.x.x):** |
| 43 | +- Exported all branches by default |
| 44 | + |
| 45 | +**After (2.x.x-beta):** |
| 46 | +- Exports main branch by default |
| 47 | +- Specify `--branch` for specific branch export |
| 48 | + |
| 49 | +**Examples:** |
| 50 | + |
| 51 | +```bash |
| 52 | +# Export main branch (default behavior) |
| 53 | +csdx cm:stacks:export -d "./export-data" -k bltxxxxxx |
| 54 | + |
| 55 | +# Export specific branch |
| 56 | +csdx cm:stacks:export --branch feature-branch -d "./export-data" -k bltxxxxxx |
| 57 | + |
| 58 | +# Export using branch alias |
| 59 | +csdx cm:stacks:export --branch-alias production -d "./export-data" -k bltxxxxxx |
| 60 | +``` |
| 61 | + |
| 62 | +**Migration Action:** To export specific branches, add the `--branch` flag to your commands. |
| 63 | + |
| 64 | +### 3. 📊 Progress Manager UI (Default) |
| 65 | + |
| 66 | +**What Changed:** |
| 67 | +- Visual Progress Manager is now the default UI for export, import, clone & seed operations |
| 68 | +- Enhanced user experience with real-time progress tracking |
| 69 | +- Console logs are available as an optional mode |
| 70 | + |
| 71 | +## New Progress Manager Interface |
| 72 | + |
| 73 | +### Default Mode: Visual Progress Manager |
| 74 | + |
| 75 | +When you run the export or import commands, a visual progress interface appears. |
| 76 | + |
| 77 | +``` |
| 78 | +STACK: |
| 79 | + ├─ Settings |████████████████████████████████████████| 100% | 1/1 | ✓ Complete (1/1) |
| 80 | + ├─ Locale |████████████████████████████████████████| 100% | 1/1 | ✓ Complete (1/1) |
| 81 | +
|
| 82 | +LOCALES: |
| 83 | + └─ Locales |████████████████████████████████████████| 100% | 2/2 | ✓ Complete (2/2) |
| 84 | +
|
| 85 | +CONTENT TYPES: |
| 86 | + └─ Content types |████████████████████████████████████████| 100% | 6/6 | ✓ Complete (6/6) |
| 87 | +
|
| 88 | +ENTRIES: |
| 89 | + ├─ Entries |████████████████████████████████████████| 100% | 12/12 | ✓ Complete (12/12) |
| 90 | +``` |
| 91 | + |
| 92 | +### Optional Mode: Console Logs |
| 93 | + |
| 94 | +For debugging or detailed logging, switch to console log mode: |
| 95 | + |
| 96 | +**Enable Console Logs:** |
| 97 | +```bash |
| 98 | +csdx config:set:log --show-console-logs |
| 99 | +``` |
| 100 | + |
| 101 | +**Disable Console Logs (back to Progress Manager):** |
| 102 | +```bash |
| 103 | +csdx config:set:log --no-show-console-logs |
| 104 | +``` |
| 105 | + |
| 106 | +**Console Log Output Example:** |
| 107 | +``` |
| 108 | +[2025-08-22 16:12:23] INFO: Exporting content from branch main |
| 109 | +[2025-08-22 16:12:23] INFO: Started to export content, version is 2 |
| 110 | +[2025-08-22 16:12:23] INFO: Exporting module: stack |
| 111 | +[2025-08-22 16:12:24] INFO: Exporting stack settings |
| 112 | +[2025-08-22 16:12:25] SUCCESS: Exported stack settings successfully! |
| 113 | +``` |
| 114 | + |
| 115 | +## Troubleshooting |
| 116 | + |
| 117 | +### Common Issues |
| 118 | + |
| 119 | +**1. Command not found errors:** |
| 120 | +- Ensure you have installed the 2.x.x-beta version |
| 121 | +- Clear npm cache: `npm cache clean --force` |
| 122 | + |
| 123 | +**2. Missing branch content:** |
| 124 | +- Check if you need to specify the `--branch` flag for non-main branches |
| 125 | +- Verify the branch exists in your stack |
| 126 | + |
| 127 | +**3. Progress display issues:** |
| 128 | +- Try switching between console logs and progress manager modes |
| 129 | +- Check terminal compatibility for progress bars |
| 130 | + |
| 131 | +**4. Performance differences:** |
| 132 | +- The 2.x.x-beta version should be faster due to TypeScript modules |
| 133 | +- If you are experiencing issues, switch to console log mode for debugging |
| 134 | + |
| 135 | +### Getting Help |
| 136 | + |
| 137 | +**Documentation:** |
| 138 | +- [CLI Documentation](https://www.contentstack.com/docs/developers/cli) |
| 139 | +- [API Reference](https://www.contentstack.com/docs/developers/apis) |
| 140 | + |
| 141 | +**Support:** |
| 142 | +- [GitHub Issues](https://github.com/contentstack/cli/issues) |
| 143 | + |
| 144 | +## Benefits of 2.x.x-beta |
| 145 | + |
| 146 | +### 🚀 **Performance Improvements** |
| 147 | +- Faster export/import operations with TypeScript modules |
| 148 | +- Optimized branch handling |
| 149 | +- Reduced memory usage |
| 150 | + |
| 151 | +### 🎯 **Better User Experience** |
| 152 | +- Visual Progress Manager with real-time updates |
| 153 | +- Cleaner command syntax |
| 154 | +- More intuitive default behaviors |
| 155 | + |
| 156 | +### 🔧 **Enhanced Reliability** |
| 157 | +- Improved error handling |
| 158 | +- Better progress tracking |
| 159 | +- More consistent behavior across commands |
| 160 | + |
| 161 | +### 📊 **Better Observability** |
| 162 | +- Detailed progress information |
| 163 | +- Clear success/failure indicators |
| 164 | +- Optional detailed logging for debugging |
| 165 | +--- |
| 166 | + |
| 167 | +**Need help with migration?** Contact our support team or visit our community forum for assistance. |
0 commit comments