@ekaone/prompt-kit

A lightweight, zero-dependency prompt template engine for Node.js. Build dynamic AI prompts from inline strings or .md files with YAML frontmatter support.

Installation

npm install @ekaone/prompt-kit

pnpm add @ekaone/prompt-kit

yarn add @ekaone/prompt-kit

bun add @ekaone/prompt-kit

Features

• {{variable}} injection with strict or passthrough mode
• YAML frontmatter parser — zero dependencies, hand-rolled
• File-based prompt loading from .md files
• Minifier to strip comments and collapse whitespace
• Lifecycle hooks — onSuccess and onError
• Zero dependencies
• ESM + CJS dual output
• TypeScript-first

Quick Start

import { build } from "@ekaone/prompt-kit";

const prompt = build(
  "You are a {{role}} assistant. Help the user with {{topic}}.",
  { role: "TypeScript", topic: "code review" }
);

console.log(prompt);
// → "You are a TypeScript assistant. Help the user with code review."

API

build(template, vars, options?)

Injects variables into a template string and returns the built prompt.

import { build } from "@ekaone/prompt-kit";

const prompt = build(
  "Summarize {{topic}} in {{words}} words.",
  { topic: "Rust", words: "100" }
);

Parameters

Parameter	Type	Description
template	string	Prompt string with {{var}} placeholders
vars	Vars	Key-value map of variable values
options	BuildOptions	Optional config (see below)

BuildOptions

Option	Type	Default	Description
strict	boolean	true	Throw on undefined variables
onSuccess	(result: string) => void	—	Called after a successful build
onError	(error: Error) => void	—	Called when build throws

Strict mode (default)

Throws if a variable is referenced in the template but not provided in vars.

build("Hello {{name}}", {});
// → Error: [prompt-kit] Undefined variable: "{{name}}"

Passthrough mode

Leaves undefined {{variables}} intact in the output.

const prompt = build(
  "Hello {{name}}, your score is {{score}}.",
  { name: "Eka" },
  { strict: false }
);
// → "Hello Eka, your score is {{score}}."

Lifecycle hooks

const prompt = build(
  "Review {{language}} code.",
  { language: "TypeScript" },
  {
    onSuccess: (result) => console.log("Built:", result.length, "chars"),
    onError: (err) => console.error("Failed:", err.message),
  }
);

---

buildFromFile(filePath, vars, options?)

Loads a .md file, parses the frontmatter, and builds the prompt from the body.

import { buildFromFile } from "@ekaone/prompt-kit";

const prompt = await buildFromFile("./prompts/review.md", {
  language: "TypeScript",
  focus: "type safety",
});

Prompt file format — ./prompts/review.md

---
name: code-review
version: 1
tags: [typescript, review]
---
You are a senior {{language}} engineer.
Review the code for correctness, performance, and style.
Focus on: {{focus}}.

---

loadPromptFile(filePath)

Reads and parses a .md file, returning frontmatter and body separately. Useful for reading metadata without triggering a build.

import { loadPromptFile } from "@ekaone/prompt-kit";

const { frontmatter, body } = await loadPromptFile("./prompts/review.md");

console.log(frontmatter.name);    // → "code-review"
console.log(frontmatter.version); // → 1
console.log(frontmatter.tags);    // → ["typescript", "review"]
console.log(body);                // → "You are a senior {{language}} engineer..."

---

parseFrontmatter(source)

Parses a raw markdown string into { frontmatter, body }. Useful when you load file content yourself.

import { parseFrontmatter } from "@ekaone/prompt-kit";

const source = `---
name: summarizer
model: claude-opus-4-5
---
Summarize the following: {{input}}`;

const { frontmatter, body } = parseFrontmatter(source);

Supported frontmatter value types

Type	Example
String	name: code-review
Number	version: 1
Boolean	strict: true
Array	tags: [a, b, c]

---

minify(input)

Strips Markdown comments and collapses excess blank lines. Useful for reducing token usage before sending to an AI SDK.

import { buildFromFile, minify } from "@ekaone/prompt-kit";

const raw = await buildFromFile("./prompts/verbose.md", vars);
const prompt = minify(raw);

Strips [//]: # (internal note) style comments and collapses 3+ blank lines into one.

---

Types

type Vars = Record<string, string | number | boolean>;

interface BuildOptions {
  strict?: boolean;
  onSuccess?: (result: string) => void;
  onError?: (error: Error) => void;
}

interface FrontMatter {
  [key: string]: string | number | boolean | string[];
}

interface ParsedPrompt {
  frontmatter: FrontMatter;
  body: string;
}

---

Real-world pattern

import { buildFromFile, minify } from "@ekaone/prompt-kit";
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const prompt = minify(
  await buildFromFile("./prompts/review.md", {
    language: "TypeScript",
    focus: "type safety",
  })
);

const response = await client.messages.create({
  model: "claude-opus-4-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: prompt }],
});

---

License

MIT © Eka Prasetia

Links

• npm Package
• GitHub Repository
• Issue Tracker

---

⭐ If this library helps you, please consider giving it a star on GitHub!