linear-upgrade-migration

Upgrade Linear SDK versions and migrate breaking changes.Use when updating to a new SDK version, handling deprecations,or migrating between major Linear API versions.Trigger with phrases like "upgrade linear SDK", "linear SDK migration","update linear", "linear breaking changes", "linear deprecation".

⭐939stars🔀114forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill streamlines the process of upgrading Linear SDK versions and managing complex migrations. It helps developers identify breaking changes, automate the refactoring of deprecated fields, and implement compatibility layers to ensure a stable transition between major API versions while maintaining code quality and type safety.

Use Cases

  • Case 1: Migrating from CommonJS to ESM (Module) support when upgrading from Linear SDK 1.x to 2.x.
  • Case 2: Refactoring code to handle breaking changes in return types, such as transitioning from direct object returns to paginated connections.
  • Case 3: Implementing a compatibility layer (wrapper) to support both old and new SDK behaviors during a gradual production rollout.
  • Case 4: Automating the detection and resolution of TypeScript errors caused by stricter type definitions in newer SDK versions.
  • Case 5: Safely handling renamed fields and new required parameters in the Linear API to prevent runtime failures.
namelinear-upgrade-migration
description|
allowed-toolsRead, Write, Edit, Bash(npm:*), Bash(npx:*), Grep
version1.0.0
licenseMIT
authorJeremy Longshore <jeremy@intentsolutions.io>

Linear Upgrade Migration

Overview

Safely upgrade Linear SDK versions and handle breaking changes.

Prerequisites

  • Existing Linear integration
  • Version control (Git) configured
  • Test suite for Linear operations

Instructions

Step 1: Check Current Version

# Check installed version
npm list @linear/sdk

# Check latest available version
npm view @linear/sdk version

# Check changelog
npm view @linear/sdk changelog

Step 2: Review Breaking Changes

# View version history
npm view @linear/sdk versions --json | jq -r '.[-10:][]'

# Check GitHub releases for migration guides
open https://github.com/linear/linear/releases

Step 3: Create Upgrade Branch

git checkout -b upgrade/linear-sdk-vX.Y.Z

Step 4: Update SDK

# Upgrade to latest
npm install @linear/sdk@latest

# Or upgrade to specific version
npm install @linear/sdk@X.Y.Z

# Check for type errors
npx tsc --noEmit

Step 5: Common Migration Patterns

Pattern A: Renamed Fields

// Before (deprecated)
const issue = await client.issue("ABC-123");
console.log(issue.state); // Old field name

// After (new version)
const issue = await client.issue("ABC-123");
const state = await issue.state; // Now returns Promise
console.log(state?.name);

Pattern B: Changed Return Types

// Before: Direct object return
const teams = await client.teams();
teams.forEach(team => console.log(team.name));

// After: Paginated connection
const teams = await client.teams();
teams.nodes.forEach(team => console.log(team.name));

Pattern C: New Required Parameters

// Before
await client.createIssue({ title: "Issue" });

// After: teamId is required
await client.createIssue({
  title: "Issue",
  teamId: team.id, // Now required
});

Pattern D: Removed Methods

// Check if method exists before using
if (typeof client.deprecatedMethod === "function") {
  await client.deprecatedMethod();
} else {
  await client.newMethod();
}

Step 6: Create Compatibility Layer

// lib/linear-compat.ts
import { LinearClient, Issue } from "@linear/sdk";

// Wrapper for breaking changes
export class LinearCompatClient {
  private client: LinearClient;

  constructor(apiKey: string) {
    this.client = new LinearClient({ apiKey });
  }

  // Normalize different SDK versions
  async getIssue(identifier: string): Promise<{
    id: string;
    title: string;
    stateName: string;
  }> {
    const issue = await this.client.issue(identifier);
    const state = await issue.state;

    return {
      id: issue.id,
      title: issue.title,
      stateName: state?.name ?? "Unknown",
    };
  }

  // Add backward-compatible methods as needed
}

Step 7: Run Tests

# Run test suite
npm test

# Run type checking
npx tsc --noEmit

# Run linting
npm run lint

Step 8: Test in Staging

# Deploy to staging
npm run deploy:staging

# Run integration tests against staging
npm run test:integration

Step 9: Gradual Rollout

// Feature flag for new SDK behavior
const USE_NEW_SDK = process.env.LINEAR_SDK_V2 === "true";

async function getIssues() {
  if (USE_NEW_SDK) {
    // New SDK logic
    return newGetIssues();
  } else {
    // Legacy SDK logic
    return legacyGetIssues();
  }
}

Version Compatibility Matrix

SDK Version Node.js TypeScript Key Changes
1.x 14+ 4.5+ Initial release
2.x 16+ 4.7+ ESM support
3.x 18+ 5.0+ Strict types

Common Breaking Changes

SDK 1.x to 2.x

// 1.x: CommonJS
const { LinearClient } = require("@linear/sdk");

// 2.x: ESM
import { LinearClient } from "@linear/sdk";

// Update package.json
{
  "type": "module"
}

SDK 2.x to 3.x

// 2.x: Loose types
const issue: any = await client.issue("ABC-123");

// 3.x: Strict types
const issue: Issue = await client.issue("ABC-123");
// Must handle nullable fields
const state = await issue.state;
if (state) {
  console.log(state.name);
}

Rollback Procedure

# If upgrade fails, rollback
git checkout main
npm install @linear/sdk@PREVIOUS_VERSION
npm run test
git commit -am "Rollback Linear SDK to PREVIOUS_VERSION"

Error Handling During Migration

Error Cause Solution
Property does not exist Renamed field Check migration guide
Type not assignable Changed type Update type annotations
Module not found ESM/CJS mismatch Update import syntax
Runtime method missing Version mismatch Check SDK version

Resources

Next Steps

Set up CI/CD integration with linear-ci-integration.