@showtheworld/typed-eleventy

A typed companion wrapper around @11ty/eleventy. It re-exports the real Eleventy runtime and adds a conservative TypeScript surface for the documented programmatic API and commonly used configuration API methods.

This package does not reimplement Eleventy or type Eleventy internals.

The published declaration files include JSDoc comments for the programmatic API, config API, callback shapes, and forwarded plugin exports so editors can show inline usage hints while you work.

AI Implementation Notice

This package was implemented with AI assistance and is intended to be maintained periodically with AI-assisted review against Eleventy releases, source code, and public documentation.

That provenance is part of the project’s operating model. The package still depends on the real @11ty/eleventy runtime, mirrors Eleventy major and minor versions, and includes type tests and build checks to reduce drift. Users should adopt it with these facts in mind, pin a compatible Eleventy major/minor version, and validate it in their own project the same way they would any third-party type companion package.

Installation

Install this package with Eleventy in the same project:

npm install @showtheworld/[email protected] @11ty/[email protected]

@11ty/eleventy is a peer dependency and must match this package’s major and minor version. Patch versions belong to this project: for example, @showtheworld/[email protected] may contain wrapper type fixes while still targeting the Eleventy 3.1 API.

Programmatic Usage

import Eleventy from "@showtheworld/typed-eleventy";

const elev = new Eleventy("src", "_site", {
  quietMode: true,
  configPath: "eleventy.config.js",
});

await elev.write();

Read build output without writing files:

import Eleventy, { type EleventyJsonEntry } from "@showtheworld/typed-eleventy";

const elev = new Eleventy();

const json: EleventyJsonEntry[] = await elev.toJSON();
const stream: NodeJS.ReadableStream = await elev.toNDJSON();

The named runtime export is also available:

import { Eleventy } from "@showtheworld/typed-eleventy";

const elev = new Eleventy(".", "_site");

Common named plugin exports from Eleventy are forwarded too:

import Eleventy, { RenderPlugin } from "@showtheworld/typed-eleventy";

const elev = new Eleventy(".", "_site", {
  config(eleventyConfig) {
    eleventyConfig.addPlugin(RenderPlugin);
  },
});

Typed Config Usage

Use defineConfig to preserve your config function while giving eleventyConfig a useful type:

import { defineConfig } from "@showtheworld/typed-eleventy";

export default defineConfig((eleventyConfig) => {
  eleventyConfig.addPassthroughCopy("public");

  eleventyConfig.addFilter("uppercase", (value: string) => {
    return value.toUpperCase();
  });

  eleventyConfig.addShortcode("year", () => new Date().getFullYear());
  eleventyConfig.addPairedAsyncShortcode("asyncBlock", async (content) => {
    return content;
  });

  eleventyConfig.addCollection("posts", (collectionApi) => {
    return collectionApi.getFilteredByGlob("posts/*.md");
  });

  eleventyConfig.addTransform("htmlmin", (content, outputPath) => {
    return outputPath?.endsWith(".html") ? content.trim() : content;
  });

  return {
    dir: {
      input: "src",
      output: "_site",
    },
    templateFormats: ["md", "njk"],
  };
});

You can also pass a typed config function directly to the programmatic constructor:

import Eleventy from "@showtheworld/typed-eleventy";

const elev = new Eleventy(".", "_site", {
  config(eleventyConfig) {
    eleventyConfig.addGlobalData("site", {
      title: "My site",
    });
  },
});

Current Limitations

Eleventy’s configuration API is intentionally dynamic. This package starts with the documented programmatic methods, commonly used configuration methods, basic collection and JSON result types, and safe extension points using unknown.

The EleventyConfig surface is based on Eleventy’s public UserConfig methods in the v3 source, including universal and template-language-specific filters, shortcodes, paired shortcodes, transforms, linters, preprocessors, plugins, virtual templates, data extensions, watch/server options, and directory setters.

Callback arguments for filters, shortcodes, events, and template render functions are intentionally loose because Eleventy passes arbitrary template data through those hooks.

The package does not type private classes, internal options, template engine internals, or plugin-specific APIs.

Compatibility Policy

This package mirrors Eleventy’s major and minor versions:

• @showtheworld/[email protected] supports Eleventy’s 3.1 API.
• Major and minor versions track Eleventy API changes. A future Eleventy 3.2.x release should be mirrored by @showtheworld/[email protected].
• Patch versions are reserved for this package’s own fixes, documentation updates, and further adaptation to the current Eleventy major/minor line.
• Eleventy patch releases are expected not to change the public API, but dependency targets should still be reviewed and updated intentionally when adopting them.
• Beta, canary, and alpha releases should only be mirrored intentionally.

Types are designed to expand gradually as public APIs are documented or verified in Eleventy source. Additive fields and methods should be non-breaking; stricter callback or option typing should be introduced cautiously so existing Eleventy projects keep compiling.

Before publishing or updating to a new Eleventy release, run:

npm run check:eleventy-version
npm test

To mirror a future Eleventy major or minor release, update the package version’s major/minor and the Eleventy dependency targets together. The patch numbers do not need to match:

{
  "version": "x.y.<typed-eleventy-patch>",
  "peerDependencies": {
    "@11ty/eleventy": "x.y.<eleventy-patch>"
  },
  "devDependencies": {
    "@11ty/eleventy": "x.y.<eleventy-patch>"
  }
}

Development

npm run check:eleventy-version
npm run build
npm test