TypeScript/JavaScript SDK patterns and best practices for Linear.
Use when learning SDK idioms, implementing common patterns,
or optimizing Linear API usage.
Trigger with phrases like "linear SDK patterns", "linear best practices",
"linear typescript", "linear API patterns", "linear SDK idioms".
Production patterns for @linear/sdk. The SDK wraps Linear's GraphQL API with strongly-typed models, cursor-based pagination (fetchNext()/fetchPrevious()), lazy-loaded relations, and typed error classes. Understanding these patterns avoids N+1 queries and rate limit waste.
Prerequisites
@linear/sdk installed
TypeScript project with strict: true
Understanding of async/await and GraphQL concepts
Instructions
Pattern 1: Client Singleton
import { LinearClient } from "@linear/sdk";
let _client: LinearClient | null = null;
export function getLinearClient(): LinearClient {
if (!_client) {
const apiKey = process.env.LINEAR_API_KEY;
if (!apiKey) throw new Error("LINEAR_API_KEY is required");
_client = new LinearClient({ apiKey });
}
return _client;
}
// For multi-user OAuth apps — one client per user
const clientCache = new Map<string, LinearClient>();
export function getClientForUser(userId: string, accessToken: string): LinearClient {
if (!clientCache.has(userId)) {
clientCache.set(userId, new LinearClient({ accessToken }));
}
return clientCache.get(userId)!;
}
Pattern 2: Cursor-Based Pagination
Linear uses Relay-style cursor pagination. The SDK provides fetchNext() and fetchPrevious() helpers, plus raw pageInfo for manual control.
// SDK built-in pagination helpers
const firstPage = await client.issues({ first: 50 });
console.log(`Page 1: ${firstPage.nodes.length} issues`);
if (firstPage.pageInfo.hasNextPage) {
const secondPage = await firstPage.fetchNext();
console.log(`Page 2: ${secondPage.nodes.length} issues`);
}
// Manual pagination with cursor — good for streaming all data
async function* paginateAll<T>(
fetchPage: (cursor?: string) => Promise<{
nodes: T[];
pageInfo: { hasNextPage: boolean; endCursor: string };
}>
): AsyncGenerator<T> {
let cursor: string | undefined;
let hasNext = true;
while (hasNext) {
const page = await fetchPage(cursor);
for (const node of page.nodes) yield node;
hasNext = page.pageInfo.hasNextPage;
cursor = page.pageInfo.endCursor;
}
}
// Stream all issues without loading everything into memory
for await (const issue of paginateAll(c => client.issues({ first: 50, after: c }))) {
console.log(`${issue.identifier}: ${issue.title}`);
}
Pattern 3: Relation Loading (Avoiding N+1)
SDK models lazy-load relations. Accessing .assignee triggers a separate API call. Use raw GraphQL to batch-fetch relations in one request.
// LAZY (N+1 problem) — each .assignee is a separate API call
const issues = await client.issues({ first: 50 });
for (const issue of issues.nodes) {
const assignee = await issue.assignee; // API call per issue!
console.log(`${issue.identifier}: ${assignee?.name}`);
}
// BATCH (1 request) — use rawRequest for precise field selection
const response = await client.client.rawRequest(`
query TeamIssues($teamKey: String!) {
issues(first: 50, filter: { team: { key: { eq: $teamKey } } }) {
nodes {
id identifier title priority
assignee { name email }
state { name type }
labels { nodes { name color } }
project { name }
}
}
}
`, { teamKey: "ENG" });
// PRE-RESOLVE — parallel resolution for a single issue
async function enrichIssue(issue: any) {
const [assignee, state, team, labels] = await Promise.all([
issue.assignee,
issue.state,
issue.team,
issue.labels(),
]);
return { ...issue, _assignee: assignee, _state: state, _team: team, _labels: labels.nodes };
}
Pattern 4: Filtering with Comparators
Linear supports eq, neq, in, nin, lt, lte, gt, gte, startsWith, contains, and logical and/or operators.
