@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 and includes type tests and build checks to reduce drift. Users should adopt it with these facts in mind, install the declared Eleventy peer dependency, 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/typed-eleventy @11ty/[email protected]

This package has its own release versions, independent of Eleventy. Compatibility is declared by peerDependencies["@11ty/eleventy"] in package.json, currently pinned to 3.1.6. Use the peer dependency declared by the wrapper release you install to choose your Eleventy version.

Programmatic Usage

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

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

await elev.write();

Eleventy is both the constructor and the instance type, with typed methods and their JSDoc available to editors. You can use it directly in annotations without InstanceType<typeof Eleventy>:

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

const elev: Eleventy = new Eleventy("src", "_site");

async function build(site: Eleventy): Promise<void> {
  await site.write();
}

This also works with the named Eleventy export. If you only need the instance type, use import type { Eleventy } from "@showtheworld/typed-eleventy".

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.

Versioning and Compatibility

This package follows its own semantic versioning:

• Major releases contain breaking changes to this wrapper's public API, types, or supported dependencies.
• Minor releases add backward-compatible functionality or type coverage.
• Patch releases contain backward-compatible fixes and documentation updates.

The wrapper's version does not identify the supported Eleventy version. The Eleventy peer dependency is the source of truth for compatibility; the development dependency pins the same exact stable release so checks run against that version. The current target is Eleventy 3.1.6.

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 adopt another Eleventy release, review its public API, update the peer and development dependency pins together, refresh package-lock.json, and update the types, tests, and compatibility information above. Choose this package's next version based on the impact on its consumers.

check:eleventy-version verifies that the declared and installed Eleventy versions match. It does not compare them with this package's version.

Development

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