TypeScript type definitions for developing Quarto execution engines.

The goal in a couple of releases is for you to be able to do

npm install @quarto/types

But this package is not published yet, because the interfaces are still in flux.

Instead, build the package and copy dist/index.d.ts to types/quarto-types.d.ts in your engine repo.

npm run build

This package provides TypeScript type definitions for implementing custom execution engines for Quarto.

import { ExecutionEngine, EngineProjectContext } from "@quarto/types";

export const customEngine: ExecutionEngine = {
  name: "custom",
  defaultExt: ".qmd",

  // Implement required methods...

  target: (
    file: string,
    quiet: boolean | undefined,
    markdown: MappedString | undefined,
    project: EngineProjectContext // Using the restricted context interface
  ) => {
    // Implementation...
  },
};

Interface for implementing a Quarto execution engine discovery, responsible for determining which engine should handle a file and launching engine instances.

Interface for a launched execution engine that can execute documents within a project context.

Restricted version of Quarto's ProjectContext that only exposes functionality needed by execution engines.

This package is designed to be a standalone, lightweight type library for external engine development. To maintain this independence, some internal Quarto types are intentionally simplified:

• RenderOptions: The internal Quarto version includes a services: RenderServices field, which provides access to temp file context, extension context, and notebook context. This field has been omitted as it requires pulling in large portions of Quarto's internal type system. All other fields are included. See src/command/render/types.ts for the full type.

• Format.render: The full internal type is FormatRender with 100+ lines of specific rendering options including brand configuration and CSS handling. See src/config/types.ts.

• Format.execute: The full internal type is FormatExecute with specific execution options. See src/config/types.ts.

• Format.pandoc: The full internal type is FormatPandoc with 80+ lines of pandoc-specific options. Simplified to { to?: string; [key: string]: unknown } preserving only the most commonly accessed to property. See src/config/types.ts.

When accessing properties from these records, use type assertions as needed:

const figFormat = options.format.execute["fig-format"] as string | undefined;
const keepHidden = options.format.render?.["keep-hidden"] as
  | boolean
  | undefined;
const writer = options.format.pandoc.to; // Type-safe access to 'to'
const standalone = options.format.pandoc["standalone"] as boolean | undefined;

The full internal Format interface includes several optional functions that are used internally by Quarto but are not needed by external engines:

• mergeAdditionalFormats: Internal format merging logic
• resolveFormat: Format resolution and normalization
• formatExtras: Compute format-specific extras (requires RenderServices and ProjectContext)
• formatPreviewFile: Preview file name transformation
• extensions: Format-specific extension configuration

These functions require deep integration with Quarto's internal systems and are not exposed to external engines. See src/config/types.ts for the full Format interface.

MIT