Configuration API (UserConfig) types, TypeScript mega issue for 3.0

[zachleat]

(This one is just a reminder for me)

See: https://www.11ty.dev/docs/config/#type-definitions

Pre-alpha I can confirm that v9 (ESM) of eleventy-base-blog with npm installed via file:../eleventy works fine but I want to remind myself to check post-publish too.

[rubenwardy]

This doesn't work for me:

import { UserConfig } from "@11ty/eleventy";

I need to do:

import UserConfig from "@11ty/eleventy/src/UserConfig.js";

---

[11ty] 1. Error in your Eleventy config file '.eleventy.js'. (via EleventyConfigError)
[11ty] 2. The requested module '@11ty/eleventy' does not provide an export named 'UserConfig' (via SyntaxError)
[11ty] 
[11ty] Original error stack trace: file:///home/ruben/dev/web/blog/plugins/wordcount.js:1
[11ty] import {UserConfig} from "@11ty/eleventy";
[11ty]         ^^^^^^^^^^
[11ty] SyntaxError: The requested module '@11ty/eleventy' does not provide an export named 'UserConfig'
[11ty]     at ModuleJob._instantiate (node:internal/modules/esm/module_job:124:21)
[11ty]     at async ModuleJob.run (node:internal/modules/esm/module_job:190:5)

[rubenwardy]

see also #3127

[uncenter]

#3060 removed the .d.ts file to rely on JSDoc entirely, but the .d.ts had been exporting UserConfig (https://github.com/11ty/eleventy/blob/ecd0579a2dded6939510b7c23841388b26eb6d16/src/index.d.ts) and the issue now that is UserConfig isn't exported anywhere else. Would the fix be to export it here?

[what1s1ove]

#3060 removed the .d.ts file to rely on JSDoc entirely, but the .d.ts had been exporting UserConfig (https://github.com/11ty/eleventy/blob/ecd0579a2dded6939510b7c23841388b26eb6d16/src/index.d.ts) and the issue now that is UserConfig isn't exported anywhere else. Would the fix be to export it here?

Agree. I have tsconfig which checks all JS files (including eleventy.config.js). Now I need to manually describe all the config keys 😕

[uncenter]

#3060 removed the .d.ts file to rely on JSDoc entirely, but the .d.ts had been exporting UserConfig (ecd0579/src/index.d.ts) and the issue now that is UserConfig isn't exported anywhere else. Would the fix be to export it here?

Agree. I have tsconfig which checks all JS files (including eleventy.config.js). Now I need to manually describe all the config keys 😕

You don't have to do that, can't you just use it like /** @param { import("@11ty/eleventy/src/UserConfig.js") } eleventyConfig */ (as suggested here)?

[what1s1ove]

#3060 removed the .d.ts file to rely on JSDoc entirely, but the .d.ts had been exporting UserConfig (ecd0579/src/index.d.ts) and the issue now that is UserConfig isn't exported anywhere else. Would the fix be to export it here?

Agree. I have tsconfig which checks all JS files (including eleventy.config.js). Now I need to manually describe all the config keys 😕

You don't have to do that, can't you just use it like /** @param { import("@11ty/eleventy/src/UserConfig.js") } eleventyConfig */ (as suggested here)?

Unfortunately, no...

Today I migrated to a new version. I'm so happy that the number of cjs files is decreasing in my projects 🎉
what1s1ove/whatislove.dev#279

After migration, I encountered two issues.

1. "Replace await readFile(pathTojson) with import attributes (Node.js versions 18 and 20 are different!)". Discussed in this issue - Import attributes not yet supported (Error thrown from acorn dependency) #3128
   • https://nodejs.org/docs/latest-v18.x/api/esm.html#import-attributes
   • https://nodejs.org/docs/latest-v20.x/api/esm.html#import-attributes
2. "Replace custom type definitions for the 11ty package" – relates to this issue.

As I mentioned earlier, my project is configured in a way that TypeScript performs checks on all .js files (in fact, not only TypeScript but many other linters do the same). Before migrating the 11ty config to js, it was ignored because it had the .cjs extension.

When TypeScript encounters an import of a package that has no types, it suggests two solutions:

1. Install types separately. In our case, this is not possible, as there are no types for 11ty as a separate package (and there's no need to have them as a separate package 🤞).
2. Create custom types using declare module. However, the problem with declare module is that within this construct, you cannot import packages that don't have types (well, you can, but any such import would result in any type). It means that the @11ty/eleventy/src/UserConfig.js import cannot be used. Because of this, all types should be defined manually.

I think before migrating to ESM, this was a rare problem, as I mentioned, many linters ignored .cjs by default. Because of this, the 11ty config didn't fall under various linters (eslint, TypeScript, etc). But now, since this will be the default behavior, this problem will affect many users. It seems to me that it should be addressed by adding d.ts files to the 11ty package itself.

[murtuzaalisurti]

While migrating to 11tyv3.0.0-alpha.5, the JSDoc comments stopped working for me. It seems that in ESM, you have to explicitly specify the default export.

/** @param { import("@11ty/eleventy").UserConfig } eleventyConfig */ ❌

/** @param { (import("@11ty/eleventy/src/UserConfig").default) } eleventyConfig */ ✅

this works fine as well:

/**
 * @typedef {import('@11ty/eleventy/src/UserConfig').default} EleventyConfig
 * @typedef {import('@11ty/eleventy/src/defaultConfig').defaultConfig} EleventyReturnValue
 * @type {(eleventyConfig: EleventyConfig) => EleventyReturnValue}
 */

[zachleat]

See #3291

[zachleat]

/** @param {import("@11ty/eleventy").UserConfig} eleventyConfig */ seems to work with 3.0.0-alpha.12 (shipped by #3291).

Closing this but would appreciate further confirmation!

[what1s1ove]

Hey guys!

Does this work for anyone? It finds the import, but it is marked as any. Because of this, there are no suggestions for the config methods/properties.