linear-local-dev-loop

name	linear-local-dev-loop
description	Set up local Linear development environment and testing workflow. Use when configuring local dev, testing integrations, or setting up a development workflow with Linear webhooks. Trigger: "linear local development", "linear dev setup", "test linear locally", "linear development environment".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(npx:*), Grep
version	1.12.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","linear","testing","workflow"]
compatibility	Designed for Claude Code

Linear Local Dev Loop

Overview

Set up an efficient local development workflow for building Linear integrations. Covers project scaffolding, environment config, test utilities, webhook tunneling with ngrok, and integration testing with vitest.

Prerequisites

• Node.js 18+ with TypeScript
• @linear/sdk package
• Separate Linear workspace or team for development (recommended)
• ngrok or cloudflared for webhook tunnel testing

Instructions

Step 1: Project Scaffolding

set -euo pipefail
mkdir linear-integration && cd linear-integration
npm init -y
npm install @linear/sdk dotenv
npm install -D typescript @types/node vitest tsx

# TypeScript config
npx tsc --init --target ES2022 --module NodeNext --moduleResolution NodeNext --strict

Step 2: Environment Configuration

# .env (never commit)
cat > .env << 'EOF'
LINEAR_API_KEY=lin_api_dev_xxxxxxxxxxxx
LINEAR_WEBHOOK_SECRET=whsec_dev_xxxxxxxxxxxx
LINEAR_DEV_TEAM_KEY=DEV
NODE_ENV=development
EOF

# .env.example (commit this for onboarding)
cat > .env.example << 'EOF'
LINEAR_API_KEY=lin_api_your_key_here
LINEAR_WEBHOOK_SECRET=
LINEAR_DEV_TEAM_KEY=DEV
NODE_ENV=development
EOF

echo -e ".env\n.env.local\n.env.*.local" >> .gitignore

Step 3: Client Module with Connection Verification

// src/client.ts
import { LinearClient } from "@linear/sdk";
import "dotenv/config";

let _client: LinearClient | null = null;

export function getClient():  {
   (!_client) {
     apiKey = process..;
     (!apiKey)   ();
    _client =  ({ apiKey });
  }
   _client;
}

   (): <> {
   client = ();
   viewer =  client.;
   teams =  client.();
  .();
  .();
}