Explain how to use JSDoc with 11ty config file

[wdsrocha]

Hi 👋

Some time ago @Ryuno-Ki added JSDoc support in the following PR: #720

My question is: how to use it? It might be silly and something that anyone with basic knowledge in JSDoc knows how to do, but I have no clue on how to make it work. I've tried:

• Searching for someone who did it already, but I couldn't find it even in Ryuno-Ki public repositories
• Searching docs/tutorials on the internet. All that I found are the Ryuno PR and Include TypeScript types for configuration files #1459
• Trial and error, but failed in all attempts and I'm not sure if it's because of JSDoc, my IDE (VSCode), Eleventy or something else

Here is my last attempt

/** @type {import('@11ty/eleventy').Eleventy} */
module.exports = function (config) { 
  return {
    dir: {
      input: "src",
      output: "build",
    },
  };
};

If this isn't something straightforward and there is anything that I can do to help, please tell me. Thanks!

[paulshryock]

@wdsrocha, based on this type definition, does this work?

/** @type {import('@11ty/eleventy').TemplateConfig~TemplateConfig~config} */
module.exports = function (config) {
  // do something
}

[wdsrocha]

It does not, @paulshryock. But I've noticed that the JSDoc is missing in the build files (that is node_modules/@11ty) - could that be the problem?

[wdsrocha]

But I just found out that this seems to work

const UserConfig = require("@11ty/eleventy/src/UserConfig");

/** @param {UserConfig} config */
module.exports = function (config) {
  config.addPassthroughCopy("./src/*.css"); // this was autocompleted

  return {
    dir: {
      input: "src",
      output: "dist",
    },
  };
};

I'm just not sure if UserConfig is a subset of what this configuration parameter is supposed to be

[paulshryock]

I'm just not sure if UserConfig is a subset of what this configuration parameter is supposed to be

This seems correct.

[paulshryock]

It does not, @paulshryock. But I've noticed that the JSDoc is missing in the build files (that is node_modules/@11ty) - could that be the problem?

Shouldn't be related. I think this project only uses JSDoc to provide type definitions for those using TypeScript. But I don't think the actual documentation site is intended to be built.

[wdsrocha]

This seems correct.

It seems correct that UserConfig is only a subset of the eleventyConfig object?

Asked again because I understood that you mean that it is a subset, but I couldn't find a counterexample (that is, a method that is described in the docs but isn't available in UserConfig).

And if UserConfig is sufficient, do you think it should be added to the documentation? If yes, how?

I have a naive proposal:

Edit: {UserConfig} config is supposed to be {UserConfig} eleventyConfig

[paulshryock]

This seems correct.

It seems correct that UserConfig is only a subset of the eleventyConfig object?

I meant UserConfig seems like the correct type/interface to use. It's a user-defined configuration object.

Docs addition looks okay to me as well, though I'm not sure if there's a standard way that this type of note (about TypeScript/types) is added anywhere else in the Docs. If there is, then this note should be consistent with whatever convention is normally used.

[wes-goulet]

I opened #2091 to hopefully make this easier for consumers. With that you can import from the package without knowing the internal paths of things:

/** @param {import("@11ty/eleventy").UserConfig} eleventyConfig */
module.exports = function (eleventyConfig) { ... }

[FunctionDJ]

This seems like the leanest method right now, which is fine once you know about it:

/** @param {import("@11ty/eleventy/src/UserConfig")} eleventyConfig */
module.exports = (eleventyConfig) => {

[pdehaan]

This is the one I use (that I don't remember which repo/article I "borrowed" it from):

/**
 * @typedef {import('@11ty/eleventy/src/UserConfig')} EleventyConfig
 * @typedef {ReturnType<import('@11ty/eleventy/src/defaultConfig')>} EleventyReturnValue
 * @type {(eleventyConfig: EleventyConfig) => EleventyReturnValue}
 */
module.exports = function (eleventyConfig) { ... };

[FunctionDJ]

@pdehaan what does the return type do? :o
i thought config was simply a function that gets eleventyConfig and then we call methods on it and that's it.

[pdehaan]

@FunctionDJ https://www.11ty.dev/docs/config/

The return object lets you define your config options (like input/output/include/layout/data directories, template engines for data/markdown/html files, supported template engines, and a handful of other things).

[FunctionDJ]

@pdehaan oh wow i've done a bunch of crazy customisation using shortcodes etc but never needed the actual regular config object.
TIL!

[zachleat]

#2091 is merged!

Preliminary docs are building to https://www.11ty.dev/docs/config/#type-definitions

[zachleat]

This is an automated message to let you know that a helpful response was posted to your issue and for the health of the repository issue tracker the issue will be closed. This is to help alleviate issues hanging open waiting for a response from the original poster.

If the response works to solve your problem—great! But if you’re still having problems, do not let the issue’s closing deter you if you have additional questions! Post another comment and we will reopen the issue. Thanks!