feat: declare "types" in package.json to make consuming types easier

[wes-goulet]

Hi 👋 - long time listener, first time caller!

I like to type my javascript files using JSDoc comments. Thanks to an excellent contribution this is possible for the .eleventy.js config file 🎉 . However, it can be more discoverable/easier with a small tweak 😄 ... that's where this here PR comes.

As discussed in #2033 the the way for 11ty consumers to get types is to reach into the 11ty package internals and find the type you want. That's less than ideal for consumers and a bit fragile (if the file ever moves with a refactor or whatnot).

So this PR does 2 things:
1️⃣ - Makes an index.d.ts declaration file that can export types
2️⃣ - updates the package.json "types" property with the path to that type declaration file

So now a consuming project can import directly from the eleventy package without reaching into it to a specific file path:

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

This PR just starts with adding the UserConfig to get it up and running, but additional types can be exported from index.d.ts over time.

As a personal preference thing, I like to use typedef's to pull in all my dependency types at the top of the file, like so 👇

/**
 * @typedef { import("@11ty/eleventy").UserConfig } UserConfig
 */

/** @param {UserConfig} eleventyConfig */
module.exports = function (eleventyConfig) {

[pdehaan]

Related discussion from earlier today: #2089

[pdehaan]

Per #2089, do we want to reexport the defaultConfig as well?

 * @typedef {import("@11ty/eleventy/src/UserConfig")} EleventyConfig
 * @typedef {ReturnType<import("@11ty/eleventy/src/defaultConfig")>} EleventyReturnValue

[wes-goulet]

That's a good question, I don't think so yet. I was thinking of keeping the scope of this PR down to just setting up the initial type declaration file with the UserConfig (which is a well-defined class, making it a good initial type to export). I was thinking exporting additional types can come after this, wanted to keep this one small, easier for @zachleat to review (and hopefully merge 😄 ).

BTW, getting that EleventyReturnValue brings up a few questions... should it return a Partial of that return type (since user config doesn't require all those types, they are all optional - they get merged with the defaultConfig)? Should we make an actual explicit interface for EleventyReturnValue (the ReturnType<typeof defaultConfig> method of inferring types is missing some properties, like dir.layouts)? Does this project want to have explicitly defined types/interfaces or just let typescript infer types based on the JS? I personally like the "contract" of having explicitly defined types, but I'm just some random dude so I didn't want to include such decisions in this PR 😀

[FunctionDJ]

This would still be really cool to have because i tried JSDoc import("11ty/eleventy"). before even looking up the "official" method (see issue below) 👀
#2033 (comment)

[zachleat]

It’s happening! It’s all happening! 2.0.0-canary.19

[paulshryock]

@zachleat was this reverted or removed? As of 3.0.0-alpha.10 it seems like types is no longer set in package.json.

[chriskirknielsen]

I've noticed the same as Paul. I modified my local files to restore the feature, seems to be working as expected. It might have been an incorrect diff resolution between "types": "src/index.d.ts" and "type": "module"? (though the index.d.ts file itself also disappeared)

If it was accidental, I've raised a PR to restore this: #3291

[zachleat]

#3291 was merged and is shipping in 3.0.0-alpha.11