docs(images): Add docs for image related errors (#6463)

* docs(images): Add docs for image related errors * fix(images): Oops * Update packages/astro/src/core/errors/errors-data.ts Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> * Update packages/astro/src/core/errors/errors-data.ts Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> * Update packages/astro/src/core/errors/errors-data.ts Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> * Update packages/astro/src/core/errors/errors-data.ts Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> * Update packages/astro/src/core/errors/errors-data.ts Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> * Update packages/astro/src/core/errors/errors-data.ts Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> --------- Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>
withastro · Mar 8, 2023 · 9d48328 · 9d48328
1 parent 964d552
commit 9d48328
Show file tree

Hide file tree

Showing 4 changed files with 57 additions and 8 deletions.
diff --git a/packages/astro/src/assets/services/service.ts b/packages/astro/src/assets/services/service.ts
@@ -135,7 +135,7 @@ export const baseService: Omit<LocalImageService, 'transform'> = {
 			if (missingDimension) {
 				throw new AstroError({
 					...AstroErrorData.MissingImageDimension,
-					message: AstroErrorData.MissingImageDimension.message(missingDimension),
+					message: AstroErrorData.MissingImageDimension.message(missingDimension, options.src),
 				});
 			}
 		}

diff --git a/packages/astro/src/core/errors/errors-data.ts b/packages/astro/src/core/errors/errors-data.ts
@@ -454,26 +454,75 @@ See https://docs.astro.build/en/guides/server-side-rendering/ for more informati
 			`[paginate()] page number param \`${paramName}\` not found in your filepath.`,
 		hint: 'Rename your file to `[page].astro` or `[...page].astro`.',
 	},
+	/**
+	 * @docs
+	 * @see
+	 * - [Assets (Experimental)](https://docs.astro.build/en/guides/assets/)
+	 * - [Image component](https://docs.astro.build/en/guides/assets/#image--astroassets)
+	 * - [Image component#alt](https://docs.astro.build/en/guides/assets/#alt-required)
+	 * @description
+	 * The `alt` property allows you to provide descriptive alt text to users of screen readers and other assistive technologies. In order to ensure your images are accessible, the `Image` component requires that an `alt` be specified.
+	 *
+	 * If the image is merely decorative (i.e. doesn’t contribute to the understanding of the page), set `alt=""` so that screen readers know to ignore the image.
+	 */
 	ImageMissingAlt: {
 		title: 'Missing alt property',
 		code: 3022,
 		message: 'The alt property is required.',
 		hint: "The `alt` property is important for the purpose of accessibility, without it users using screen readers or other assistive technologies won't be able to understand what your image is supposed to represent. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-alt for more information.",
 	},
+	/**
+	 * @docs
+	 * @see
+	 * - [Image Service API](https://docs.astro.build/en/reference/image-service-reference/)
+	 * @description
+	 * There was an error while loading the configured image service. This can be caused by various factors, such as your image service not properly exporting a compatible object in its default export, or an incorrect path.
+	 *
+	 * If you believe that your service is properly configured and this error is wrong, please [open an issue](https://astro.build/issues/).
+	 */
 	InvalidImageService: {
 		title: 'Error while loading image service',
 		code: 3023,
 		message:
 			'There was an error loading the configured image service. Please see the stack trace for more information.',
 	},
+	/**
+	 * @docs
+	 * @message
+	 * Missing width and height attributes for `IMAGE_URL`. When using remote images, both dimensions are always required in order to avoid cumulative layout shift (CLS).
+	 * @see
+	 * - [Assets (Experimental)](https://docs.astro.build/en/guides/assets/)
+	 * - [Image component#width-and-height](https://docs.astro.build/en/guides/assets/#width-and-height)
+	 * @description
+	 * For remote images, `width` and `height` cannot be inferred from the original file. As such, in order to avoid CLS, those two properties are always required.
+	 *
+	 * If your image is inside your `src` folder, you probably meant to import it instead. See [the Imports guide for more information](https://docs.astro.build/en/guides/imports/#other-assets).
+	 */
 	MissingImageDimension: {
 		title: 'Missing image dimensions',
 		code: 3024,
-		message: (missingDimension: 'width' | 'height' | 'both') =>
-			`For remote images, ${
-				missingDimension === 'both' ? 'width and height are' : `${missingDimension} is`
-			} required.`,
+		message: (missingDimension: 'width' | 'height' | 'both', imageURL: string) =>
+			`Missing ${
+				missingDimension === 'both'
+					? 'width and height attributes'
+					: `${missingDimension} attribute`
+			} for ${imageURL}. When using remote images, both dimensions are always required in order to avoid CLS.`,
+		hint: 'If your image is inside your `src` folder, you probably meant to import it instead. See [the Imports guide for more information](https://docs.astro.build/en/guides/imports/#other-assets).',
 	},
+	/**
+	 * @docs
+	 * @description
+	 * The built-in image services do not currently support optimizing all image formats.
+	 *
+	 * For unsupported formats such as SVGs and GIFs, you may be able to use an `img` tag directly:
+	 * ```astro
+	 * ---
+	 * import rocket from '../assets/images/rocket.svg'
+	 * ---
+	 *
+	 * <img src={rocket.src} width={rocket.width} height={rocket.height} alt="A rocketship in space." />
+	 * ```
+	 */
 	UnsupportedImageFormat: {
 		title: 'Unsupported image format',
 		code: 3025,

diff --git a/packages/astro/test/core-image.test.js b/packages/astro/test/core-image.test.js
@@ -125,7 +125,7 @@ describe('astro:image', () => {
 				await res.text();
 
 				expect(logs).to.have.a.lengthOf(1);
-				expect(logs[0].message).to.contain('For remote images, width and height are required.');
+				expect(logs[0].message).to.contain('Missing width and height attributes');
 			});
 
 			it('error if no height', async () => {
@@ -134,7 +134,7 @@ describe('astro:image', () => {
 				await res.text();
 
 				expect(logs).to.have.a.lengthOf(1);
-				expect(logs[0].message).to.contain('For remote images, height is required.');
+				expect(logs[0].message).to.contain('Missing height attribute');
 			});
 
 			it('supports aliases', async () => {

diff --git a/packages/webapi/mod.d.ts b/packages/webapi/mod.d.ts
@@ -10,4 +10,4 @@ interface PolyfillOptions {
     override?: Record<string, {
         (...args: any[]): any;
     }>;
-}
+}