Prompt Engineering with TypeScript | Code Card

Introduction to prompt engineering for TypeScript developers

Prompt engineering for TypeScript is less about clever phrasing and more about crafting precise constraints that drive type-safe output. With static types, generics, and strict compiler settings, you can give AI systems a reliable target and reduce the amount of back-and-forth needed to reach production-ready code. When the model understands your runtime, framework stack, and type expectations, the first draft compiles more often, and refactors are safer.

TypeScript brings unique leverage to AI-assisted JavaScript development. Clear function signatures, Zod or io-ts schemas, and consistent tsconfig settings convert fuzzy requests into structured instructions. Use these strengths to steer assistants like Claude Code toward deterministic outputs, lower token usage, and faster iteration. If you want to analyze how your prompt-engineering habits affect compile success and throughput over time, you can publish those AI coding stats to a public profile with Code Card.

Language-specific considerations for TypeScript prompt-engineering

Make the type system explicit in your prompts

Specify your TypeScript version, tsconfig essentials, and strictness level. Models tend to produce safer patterns when you state strict: true, target ECMAScript level, and module settings.
Provide function signatures or TypeScript interfaces up front. Ask for implementations that satisfy the signature and pass a short test. This improves compile-rate on the first attempt.
Prefer type-centric acceptance criteria. For example: "The output must satisfy Result<User, ValidationError>, no any, and pass tsc --noEmit."

Leverage runtime validation

Structured prompting works best when you enforce runtime contracts. Zod and io-ts help you validate AI responses and keep your pipeline resilient.

// zod-schemas.ts
import { z } from "zod";

export const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  roles: z.array(z.enum(["admin", "editor", "viewer"])).default(["viewer"]),
});

export type User = z.infer<typeof UserSchema>;

In your prompt, include the schema or a minimal version of it. Then instruct the model to produce JSON that conforms to the schema. Validate the result before using it.

Framework-aware instructions

React and Next.js: Specify major versions, React Server Components usage, and routing conventions. For Next.js App Router, request file-system routes and async server components only where appropriate.
NestJS and Express: Ask for controllers, providers, and DTOs with class-validator decorators or Zod schemas. For Express, request middleware composition and typed request handlers.
Data layer: If using Prisma, include your prisma schema snippet and ask the model to generate type-safe queries. If using tRPC, describe the router structure and inference flow.

Patterns that differ from plain JavaScript

Type-driven design: Prefer prompts that ask for types, then implementations. In dynamic JavaScript, you might ask for a quick example. In TypeScript, ask for a signature and constraints first.
Testing strategy: Request type tests with tsd or compile-time assertions, in addition to runtime tests with Jest or Vitest.
Refactors: Instruct the model to maintain generic constraints and type inference stability during refactors. For example: "Preserve <T extends string | number> generic bounds."

Key metrics and benchmarks for TypeScript AI workflows

To evaluate prompt-engineering quality in TypeScript, track metrics that reflect type safety, maintainability, and editing efficiency.

First-compile success rate: Percentage of AI-generated diffs that pass tsc --noEmit on the first run. Benchmark target: 70 percent or higher with mature prompts.
ESLint pass rate: Percentage of changesets that pass ESLint with your standard config. Target 80 percent or higher once rules are well-specified in the prompt.
Type coverage: Track noImplicitAny violations and any usage count. Target less than 2 new any per 1,000 lines of AI-generated code.
Test pass rate: Percentage of tests passing on first run after generation or refactor. Aim for 90 percent on stable modules, 70 percent on new modules.
JSON or tool output validity: If you ask for structured outputs, measure parse success rate and schema validation success. Target 95 percent for stable schemas.
Token efficiency: Tokens consumed per accepted line of code. Lower is better. Stable workflows often reach 2-5 tokens per accepted character of final code across iterations.
Round-trip count: Number of prompt-response cycles before code is merge-ready. Well-scoped tasks often fit in 1-2 cycles.

Automate measurement with scripts

// scripts/metrics.ts
import { execSync } from "node:child_process";
import fs from "node:fs";

type Metrics = {
  timestamp: string;
  compileOk: boolean;
  eslintErrors: number;
  testsPassed: boolean;
  anyCount: number;
};

function run(cmd: string) {
  try {
    return { stdout: execSync(cmd, { stdio: "pipe" }).toString(), ok: true };
  } catch (e: any) {
    return { stdout: e.stdout?.toString?.() ?? "", ok: false };
  }
}

function countAny(): number {
  // naive count - replace with ts-morph or eslint rule for precision
  const files = execSync('git ls-files "*.ts" "*.tsx"').toString().split("\n").filter(Boolean);
  let count = 0;
  for (const f of files) {
    const src = fs.readFileSync(f, "utf8");
    count += (src.match(/\bany\b/g) ?? []).length;
  }
  return count;
}

const tsc = run("npx tsc --noEmit");
const eslint = run("npx eslint . --ext .ts,.tsx -f json");
let eslintErrors = 0;

try {
  const report = JSON.parse(eslint.stdout || "[]");
  eslintErrors = report.reduce((acc: number, f: any) => acc + (f.errorCount || 0), 0);
} catch {
  eslintErrors = 9999;
}

const tests = run("npx vitest run --reporter=json");
const testsPassed = /\"numFailedTestSuites\":\s*0/.test(tests.stdout) && /\"numFailedTests\":\s*0/.test(tests.stdout);

const m: Metrics = {
  timestamp: new Date().toISOString(),
  compileOk: tsc.ok,
  eslintErrors,
  testsPassed,
  anyCount: countAny(),
};

fs.mkdirSync(".ai-metrics", { recursive: true });
fs.appendFileSync(".ai-metrics/history.ndjson", JSON.stringify(m) + "\n");
console.log(JSON.stringify(m, null, 2));

Run this after each AI-assisted change. The output becomes a dataset you can analyze for trends in prompt-engineering effectiveness.

Practical tips and code examples

Use a TypeScript-first instruction template

System: You are a senior TypeScript engineer.
Follow these constraints exactly:
- Target TypeScript 5.x, Node 20, strict tsconfig.
- No "any". Use precise generics and readonly where appropriate.
- Return structured JSON for tools when requested.
- Include one small focused test with Vitest.

User:
Task: Implement a rate limiter.

Constraints:
- Provide a function: createRateLimiter(limit: number, windowMs: number)
  that returns { allow: (key: string) => boolean }.
- Must be side-effect free, suitable for testing, and respect Node 20 timers.

Deliverables:
1) Type definitions and implementation.
2) A Vitest suite that covers happy path and boundary conditions.
3) No external dependencies.

Ask for types first, then implementation

// request: "Propose types, then implement"
// expected AI output fragment
export type AllowFn = (key: string, now?: number) => boolean;

export interface RateLimiter {
  readonly allow: AllowFn;
}

export function createRateLimiter(limit: number, windowMs: number): RateLimiter {
  let hits = new Map<string, number[]>();
  return {
    allow: (key, now = Date.now()) => {
      const start = now - windowMs;
      const arr = hits.get(key) ?? [];
      const pruned = arr.filter(t => t >= start);
      if (pruned.length >= limit) {
        hits.set(key, pruned);
        return false;
      }
      pruned.push(now);
      hits.set(key, pruned);
      return true;
    }
  };
}

Validate structured outputs with Zod

When you request JSON or tool results, supply the schema and require the assistant to return only valid JSON. Then validate before use.

// validator.ts
import { z } from "zod";

const ToolResult = z.object({
  tool: z.literal("summarize"),
  version: z.literal(1),
  chunks: z.array(z.object({
    id: z.string(),
    summary: z.string().min(1),
    tokens: z.number().int().nonnegative(),
  })).nonempty(),
});

type ToolResult = z.infer<typeof ToolResult>;

export function parseToolResult(json: string): ToolResult {
  const data = JSON.parse(json);
  return ToolResult.parse(data);
}

Provide few-shot examples and forbidden patterns

Show one compact before-and-after example. Keep it small so it does not overwhelm context windows.
List forbidden patterns: "No any, no mutable default params, prefer readonly, return discriminated unions for errors."
Pin libraries and versions: "Use zod@^3, vitest@^1, react@18."

Short, testable units beat monolithic requests

Split large tasks by module boundaries. Ask the model to produce one typed function and one test file per step. This improves compile and test pass rates while keeping token usage in check.

Tracking your progress and visualizing patterns

Great prompt engineering compounds over weeks. Persist your metrics and publish them so you can spot trends, celebrate streaks, and refine tactics. After logging metrics with a script, push summaries to a profile with Code Card to visualize contribution graphs, token breakdowns, and badges for type-safe output streaks.

// scripts/publish.ts
import fs from "node:fs";
import path from "node:path";

// Convert history.ndjson to a compact summary payload
function buildSummary() {
  const p = path.join(".ai-metrics", "history.ndjson");
  const lines = fs.readFileSync(p, "utf8").trim().split("\n");
  const items = lines.map(l => JSON.parse(l));

  const last30 = items.slice(-30);
  const compileRate = last30.filter((i: any) => i.compileOk).length / Math.max(1, last30.length);
  const testRate = last30.filter((i: any) => i.testsPassed).length / Math.max(1, last30.length);
  const avgAny = last30.reduce((a: number, i: any) => a + i.anyCount, 0) / Math.max(1, last30.length);

  return {
    compileRate: Number(compileRate.toFixed(2)),
    testRate: Number(testRate.toFixed(2)),
    avgAny: Math.round(avgAny),
    count: last30.length,
    ts: new Date().toISOString()
  };
}

const payload = buildSummary();
fs.writeFileSync(".ai-metrics/summary.json", JSON.stringify(payload, null, 2));
console.log("summary.json ready - publish with your CI step, or run: npx code-card");

Related guides can help broaden your approach to AI-assisted workflows:

Conclusion

Effective prompt-engineering in TypeScript comes down to constraints, type-first interfaces, and short, testable tasks. Combine clear schemas, framework-aware instructions, and automated metrics to cut cycles and grow reliability. As your metrics improve, you will see fewer compile errors, higher test pass rates, and more consistent output across React, Next.js, NestJS, and Node services. Keep iterating on your templates, and let your data guide the craft.

FAQ

How do I ask for type-safe outputs without getting verbose code?

Request explicit types and acceptance criteria, but keep implementation scope small. Ask for an interface or function signature first, then a minimal implementation and one focused test. Specify "no any, preserve inference, prefer readonly". This yields compact, type-safe code without excessive scaffolding.

What is the best way to ensure the model respects my tsconfig?

Paste a condensed version of your tsconfig in the prompt - only the keys that matter, like strict, target, module, and noUncheckedIndexedAccess. Add a constraint: "Output must compile with this tsconfig using tsc --noEmit." Then automate a compile check in your feedback loop and share the error summary back to the model when needed.

Should I include Zod or io-ts schemas in the prompt?

Yes, when you need structured data. Include the schema or a distilled version and instruct the assistant to return only valid JSON with no extra commentary. Validate with Zod or io-ts in your code. Track schema-parse success rate as a metric to tune your prompt.

How do I keep AI-generated React components idiomatic?

Specify React version, conventions like function components and hooks, and whether you use server components in Next.js. Provide one small example component that matches your style. Add forbidden patterns such as "no default exports for components" and "no inline styles unless explicitly requested". Require a quick unit test with React Testing Library.

What benchmarks indicate healthy prompt-engineering for TypeScript?

Aim for 70 percent first-compile success, 80 percent ESLint pass rate, fewer than 2 new any per 1,000 generated lines, and 90 percent test pass rate on mature modules. Keep round-trips to 1-2 for well-scoped tasks and sustain a high JSON validation success rate for structured outputs.