Merge pull request #736 from simonihmig/docs-ts

Add TS ambient declaration docs

apps/docs/src/build/vite.md

@@ -25,7 +25,7 @@ pnpm add @responsive-image/vite-plugin @responsive-image/core
 
 ## Usage
 
-This package provides several Vite plugins for specific aspects of image processing and transforming an import of an image into an ES module whose exported value you can pass to the `<ResponsiveImage/>` component.
+This package provides several Vite plugins for specific aspects of image processing and transforming an import of a [local image](../usage/local-images.md) into an ES module whose exported value you can pass to the [image component](../usage/component.md).
 
 The easiest and recommended way to set these up is to use the provided `setupPlugins` utility function:
 

apps/docs/src/build/webpack.md

@@ -25,7 +25,7 @@ pnpm add @responsive-image/webpack @responsive-image/core
 
 ## Usage
 
-This package provides several webpack loaders for specific aspects of image processing and transforming an import of an image into an ES module whose exported value you can pass to the `<ResponsiveImage/>` component.
+This package provides several webpack loaders for specific aspects of image processing and transforming an import of a [local image](../usage/local-images.md) into an ES module whose exported value you can pass to the [image component](../usage/component.md).
 
 The easiest and recommended way to set these up is to use the provided `setupLoaders` utility function:
 

apps/docs/src/frameworks/ember.md

@@ -164,20 +164,4 @@ declare module '@glint/environment-ember-loose/registry' {
 }
 ```
 
-### Image imports
-
-To make TypeScript understand your image imports, we tag them using a `responsive` query parameter, that has to come _last_!
-
-> [!NOTE]
-> We cannot use something like `*.jpg*` that works with queries, as TS only supports a single wildcard.
-> See https://github.com/microsoft/TypeScript/issues/38638
-
-Add this declaration to a file, e.g. your app's `types/global.d.ts`:
-
-```ts
-declare module '*responsive' {
-  import type { ImageData } from '@responsive-image/core';
-  const value: ImageData;
-  export default value;
-}
-```
+If you are using one of the [build plugins](../build/index.md), also make sure to have the necessary ambient declaration for image imports in place as described [here](../usage/local-images.md#typescript)!

apps/docs/src/frameworks/wc.md

@@ -36,7 +36,7 @@ import '@responsive-image/wc';
 ```
 
 > [!Important]
-> As the `src` input is an `ImageData` object, you cannot pass this as an HTML _attribute_. Web components only support string based attributes. So make sure to set it as a _property_ using JavaScript. In case of [Lit](https://lit.dev/), you would use the dot prefix notation for [property expressions](https://lit.dev/docs/templates/expressions/#property-expressions): ``html`<responsive-image .src=${image} />\` ``.
+> As the `src` input is an `ImageData` object, you cannot pass this as an HTML _attribute_. Web components only support string based attributes. So make sure to set it as a _property_ using JavaScript. In case of [Lit](https://lit.dev/), you would use the dot prefix notation for [property expressions](https://lit.dev/docs/templates/expressions/#property-expressions): ``html`<responsive-image .src=${image} ></responsive-image>\` ``.
 
 ## Local images
 

apps/docs/src/usage/component.md

@@ -134,6 +134,8 @@ import logoImage from './hero.jpg?w=320;640&responsive';
 ```
 
 ```ts [Lit]
+import logoImage from './hero.jpg?w=320;640&responsive';
+
 html`<responsive-image .src=${logoImage} with="320"></responsive-image>`;
 ```
 

apps/docs/src/usage/local-images.md

@@ -269,3 +269,21 @@ Tints the image using the provided chroma while preserving the image luminance.
 import image from 'image.jpg?tint=#ffaa22&responsive';
 import image from 'image.jpg?tint=rgba(10,33,127)&responsive';
 ```
+
+## TypeScript
+
+To make TypeScript understand your image imports, we tag them using a `responsive` query parameter, that has to come _last_!
+
+Add this ambient declaration to a file in your app, like e.g. `types/global.d.ts` (and make sure that your `tsconfig.json` includes that file!):
+
+```ts
+declare module '*responsive' {
+  import type { ImageData } from '@responsive-image/core';
+  const value: ImageData;
+  export default value;
+}
+```
+
+> [!NOTE]
+> We cannot use something like `*.jpg*` that works with queries, as TS only supports a single wildcard. That's why any image imports needs the `responsive` query parameter, and it has to come _last_!
+> See https://github.com/microsoft/TypeScript/issues/38638