Analyze, plan, and execute Lokalise SDK upgrades with breaking change detection.
Use when upgrading Lokalise SDK versions, detecting deprecations,
or migrating to new API versions.
Trigger with phrases like "upgrade lokalise", "lokalise migration",
"lokalise breaking changes", "update lokalise SDK", "analyze lokalise version".
Analyze, plan, and execute Lokalise SDK upgrades with breaking change detection.
Use when upgrading Lokalise SDK versions, detecting deprecations,
or migrating to new API versions.
Trigger with phrases like "upgrade lokalise", "lokalise migration",
"lokalise breaking changes", "update lokalise SDK", "analyze lokalise version".
Designed for Claude Code, also compatible with Codex and OpenClaw
Lokalise Upgrade Migration
Current State
!npm list @lokalise/node-api 2>/dev/null | grep lokalise || echo 'SDK not installed'
!lokalise2 --version 2>/dev/null || echo 'CLI not installed'
!node --version 2>/dev/null || echo 'Node.js not available'
!cat package.json 2>/dev/null | grep -E '"type"|"module"' || echo 'No package.json type field'
Overview
Upgrade the @lokalise/node-api SDK between major versions with full breaking change detection, automated code transformation, and verification. The most significant migration is v8 (CommonJS) to v9+ (ESM-only), which requires changes to imports, module configuration, and potentially your build pipeline.
Prerequisites
Existing project using @lokalise/node-api (any version 6.x through 9.x)
Node.js 18+ for SDK v9 (Node.js 14+ for v8 and below)
Git repository with clean working tree (for safe rollback)
Test suite that exercises Lokalise API calls
Instructions
Step 1: Assess Current Version and Target
set -euo pipefail
echo"=== Current SDK Version ==="
CURRENT=$(npm list @lokalise/node-api --json 2>/dev/null | node -e "
const d = JSON.parse(require('fs').readFileSync(0,'utf8'));
const v = d.dependencies?.['@lokalise/node-api']?.version || 'not found';
console.log(v);
")
echo"Installed: ${CURRENT}"echo -e "\n=== Latest Available ==="
LATEST=$(npm view @lokalise/node-api version)
echo"Latest: ${LATEST}"echo -e "\n=== All Major Versions ==="
npm view @lokalise/node-api versions --json | node -e "
const versions = JSON.parse(require('fs').readFileSync(0,'utf8'));
const majors = {};
versions.forEach(v => { const m = v.split('.')[0]; majors[m] = v; });
Object.entries(majors).forEach(([m, v]) => console.log(' v' + m + '.x latest: ' + v));
"
// BEFORE (v6 offset pagination)const keys = await lok.keys().list({
project_id: projectId,
page: 2,
limit: 100,
});
// AFTER (v9 cursor pagination — preferred for large datasets)const keys = await lok.keys().list({
project_id: projectId,
limit: 500,
pagination: 'cursor',
cursor: previousCursor,
});
// Access next cursor: keys.nextCursor// Check for more: keys.hasNextCursor()
Step 5: Update Error Handling
// BEFORE (v8)const { ApiError } = require('@lokalise/node-api');
try {
await lok.projects().get(projectId);
} catch (e) {
if (e instanceofApiError) {
console.error(e.message, e.code);
}
}
// AFTER (v9 — ApiError import path unchanged, but must use import)import { ApiError } from'@lokalise/node-api';
try {
await lok.projects().get(projectId);
} catch (e) {
if (e instanceofApiError) {
console.error(e.message, e.code);
}
}
Step 6: Install and Verify
set -euo pipefail
# Create a safety branch
git checkout -b upgrade/lokalise-sdk-v9
# Install the target version
npm install @lokalise/node-api@latest
# Run TypeScript compilation check
npx tsc --noEmit 2>&1 | head -40 || true# Run tests
npm test
All require() calls converted to ESM import (if upgrading to v9)
package.json and tsconfig.json updated for ESM compatibility
Pagination code migrated to cursor-based pattern
Tests passing against the new SDK version
Git branch with all changes for review
Error Handling
Issue
Cause
Solution
ERR_REQUIRE_ESM
Using require() with v9 SDK
Convert to import syntax and set "type": "module" in package.json
SyntaxError: Cannot use import
Node.js file not recognized as ESM
Rename .js to .mjs or add "type": "module"
TypeError: lok.keys is not a function
API changed between major versions
Check SDK changelog for renamed methods
ERR_UNKNOWN_FILE_EXTENSION .ts
TypeScript not configured for ESM
Use tsx runner or configure ts-node with "esm": true
Tests fail after upgrade
Breaking API changes
Check test against the version-specific migration notes above
Examples
Rollback Procedure
set -euo pipefail
# If the upgrade causes issues, revert immediately
git stash # Save any work in progress
npm install @lokalise/node-api@8 # Last CJS version
git checkout HEAD -- tsconfig.json package.json
npm testecho"Rolled back to v8. Investigate failures before retrying."
