diff --git a/.changeset/witty-poems-pull.md b/.changeset/witty-poems-pull.md new file mode 100644 index 0000000..c7db81a --- /dev/null +++ b/.changeset/witty-poems-pull.md @@ -0,0 +1,41 @@ +--- +"astro-integration-kit": minor +--- + +Simplifies emitted declarations for plugins. + +This avoids problems with too complex or non-portable types for published libraries offering plugins. Previously a simple plugin would result in a declaration like this: + +```ts +declare const hookProviderPlugin: astro_integration_kit.Plugin<"hook-provider", { + 'astro:config:setup': ({ config }: { + config: astro.AstroConfig; + command: "dev" | "build" | "preview"; + isRestart: boolean; + updateConfig: (newConfig: DeepPartial) => astro.AstroConfig; + addRenderer: (renderer: astro.AstroRenderer) => void; + addWatchFile: (path: string | URL) => void; + injectScript: (stage: astro.InjectedScriptStage, content: string) => void; + injectRoute: (injectRoute: astro.InjectedRoute) => void; + addClientDirective: (directive: astro.ClientDirectiveConfig) => void; + addDevOverlayPlugin: (entrypoint: string) => void; + addDevToolbarApp: (entrypoint: string | astro.DevToolbarAppEntry) => void; + addMiddleware: (mid: astro.AstroIntegrationMiddleware) => void; + logger: astro.AstroIntegrationLogger; + }) => { + doThing: (thing: string) => void; + }; +}; +``` + +Now, the same plugin will emit the following simplified declaration, without inlining any of the AstroHooks types: + +```ts +declare const hookProviderPlugin: astro_integration_kit.Plugin<"hook-provider", { + 'astro:config:setup': { + doThing: (thing: string) => void; + }; +}; +``` + +As shown above, this simplification also removes the unneeded re-declaration of the plugin hook input, which is a breaking change if you are declaring your generic explicitly. diff --git a/docs/astro.config.ts b/docs/astro.config.ts index 6d912e8..90ae2e6 100644 --- a/docs/astro.config.ts +++ b/docs/astro.config.ts @@ -97,7 +97,6 @@ export default defineConfig({ { label: "hmrIntegration", link: "/dev/hmr-integration/", - badge: badge("new"), }, ], }, @@ -168,7 +167,6 @@ export default defineConfig({ { label: "watchDirectory", link: "/utilities/watch-directory/", - badge: badge("new"), }, { label: "watchIntegration", diff --git a/docs/src/content/docs/getting-started/upgrade-guide.mdx b/docs/src/content/docs/getting-started/upgrade-guide.mdx index 6b01c67..6843c64 100644 --- a/docs/src/content/docs/getting-started/upgrade-guide.mdx +++ b/docs/src/content/docs/getting-started/upgrade-guide.mdx @@ -7,6 +7,30 @@ import { Tabs, TabItem } from '@astrojs/starlight/components'; Features get added and removed, and breaking changes are introduced! This documents how to migrate. +## `0.13.0` + +--- + +### `Plugin` type simplified + +The new Plugin signature added back in [`0.9.0`](#new-plugin-signature-and-defineplugin) returned the need for emitted declarations to include the full type for hook parameters from Astro (which was removed on [`0.7.0`](#plugins-types)). +This was added along with support for a plugin to define new utilities for multiple hooks at once. + +Now, the Plugin generics have been simplified again to allow for such support without having to replicate Astro's hook parameters types. Just like in `0.7.0`, this should be non-breaking for any plugin relying on type inference but plugins with explicitly declared signatures need to update the following: + +```ts del={5} ins={6} +type SomePlugin = Plugin< + "utilityName", + "astro:config:setup", + { + "astro:config:setup": (HookParameters<"astro:config:setup">) => { + "astro:config:setup": { + utilityName: (params: UtilityParams) => UtilityOutput + } + } +>; +``` + ## `0.12.0` --- diff --git a/package/src/core/types.ts b/package/src/core/types.ts index c74ea89..fddf70c 100644 --- a/package/src/core/types.ts +++ b/package/src/core/types.ts @@ -2,9 +2,11 @@ import type { DevToolbarApp } from "astro"; import type { Prettify } from "../internal/types.js"; export type PluginHooksConstraint = { - [Hook in keyof Hooks]?: ( - ...args: Parameters - ) => Record; + [Hook in keyof Hooks]?: Record; +}; + +type PluginPerHookSetup = { + [Hook in keyof THooks & keyof Hooks]: (...params: Parameters) => THooks[Hook]; }; export type Plugin< @@ -12,11 +14,11 @@ export type Plugin< THooks extends PluginHooksConstraint, > = { name: TName; - setup: (params: { name: string }) => THooks; + setup: (params: { name: string }) => PluginPerHookSetup; }; // To avoid having to call this manually for every generic -export type AnyPlugin = Plugin>; +export type AnyPlugin = Plugin>; declare global { namespace AstroIntegrationKit { @@ -41,13 +43,9 @@ type AnyFunction = (...args: Array) => any; */ type SimplifyPlugin = { name: TPlugin["name"]; - hooks: { - [K in keyof ReturnType]: ReturnType< - TPlugin["setup"] - >[K] extends AnyFunction - ? ReturnType[K]> - : never; - }; + hooks: TPlugin extends Plugin + ? THooks + : Record, }; /**