PromptL Compiler

0.12.0 verified Fri May 01 auth: no javascript

Official JavaScript/TypeScript compiler for PromptL, a language for defining dynamic LLM prompts with variables and control flow. Current version 0.12.0, actively developed by Latitude. Ships TypeScript types natively. Compiles PromptL syntax into structured JSON messages compatible with major LLM providers like OpenAI. Unlike raw template strings, PromptL provides a validated grammar, front-matter for model config, and built-in support for multi-turn conversations. Release cadence is weekly to bi-weekly. Key differentiator: human-readable prompt files with dynamic logic, compiled to provider-native formats without runtime dependencies.

Common errors

error Error: Cannot find module 'promptl-ai' ↓

cause Package is ESM-only, but project uses require() or no "type": "module" in package.json.

fix

Add "type": "module" to your package.json or use dynamic import: await import('promptl-ai')

error TypeError: compile is not a function ↓

cause Import mismatch: using default import instead of named import.

fix

Use import { compile } from 'promptl-ai' instead of import compile from 'promptl-ai'

error PromptlError: Variable "country" not found in context ↓

cause A variable used in the prompt template was not provided in the options.variables object.

fix

Pass all required variables during compilation: compile(template, { variables: { country: 'France' } })

Warnings

breaking compile() now returns an object with { messages, config } instead of a flat messages array as of v0.10.0. ↓

fix Access result.messages for the message array and result.config for model/temperature/etc.

deprecated The 'strict' option in compile() is deprecated and will be removed in v1.0. Use 'mode: 'strict' instead. ↓

fix Replace { strict: true } with { mode: 'strict' }.

gotcha Variables in PromptL are case-sensitive and must be provided exactly as declared. Undefined variables cause a runtime error unless 'mode: 'loose'' is set. ↓

fix Ensure all variables %7B%7B varName }} are provided in the options.variables object, or set mode to 'loose' to ignore missing variables.

breaking Support for Node.js < 18 removed in v0.12.0. ↓

fix Upgrade Node.js to version 18 or later.

Install

npm install promptl-ai

yarn add promptl-ai

pnpm add promptl-ai

Imports

compile

wrong

const { compile } = require('promptl-ai')

correct

import { compile } from 'promptl-ai'

ESM-only package. CJS require() will fail.

CompiledPrompt

wrong

import { CompiledPrompt } from 'promptl-ai'

correct

import type { CompiledPrompt } from 'promptl-ai'

TypeScript type import, not a runtime value.

PromptlError

wrong

import { PromptlError } from 'promptl-ai/errors'

correct

import { PromptlError } from 'promptl-ai'

Exported from the main module, not a subpath.

Quickstart

Compiles a PromptL string with variables into a provider-ready JSON object, showing variable interpolation and front-matter parsing.

import { compile } from 'promptl-ai';

const prompt = `---
model: gpt-4
temperature: 0.7
---
You are a helpful AI assistant.
<user>
  What is the capital of {{ country }}?
</user>`;

const result = compile(prompt, { variables: { country: 'France' } });
console.log(JSON.stringify(result, null, 2));
/*
{
  "model": "gpt-4",
  "temperature": 0.7,
  "messages": [
    { "role": "system", "content": "You are a helpful AI assistant." },
    { "role": "user", "content": "What is the capital of France?" }
  ]
}
*/