Document image transformer (parcel-bundler#782)

brodul · Dec 16, 2020 · c29bd1e · c29bd1e
1 parent d18f1f7
commit c29bd1e
Show file tree

Hide file tree

Showing 4 changed files with 68 additions and 2 deletions.
diff --git a/src/assets/lang-icons/image.svg b/src/assets/lang-icons/image.svg
diff --git a/src/recipes/debugging.md b/src/recipes/debugging.md
@@ -3,7 +3,7 @@ layout: layout.njk
 eleventyNavigation:
   key: recipes-debugging
   title: 🛠️ Debugging
-  order: 2
+  order: 1
 ---
 
 As Parcel automatically generates sourcemaps by default, setting up debugging with Parcel involves minimal effort for the most part.

diff --git a/src/recipes/image.md b/src/recipes/image.md
@@ -0,0 +1,61 @@
+---
+layout: layout.njk
+eleventyNavigation:
+  key: recipes-image
+  title: <img src="/assets/lang-icons/image.svg" alt=""/> Image
+  order: 2
+---
+
+Image assets can be imported and processed like any other asset in Parcel. As with any other asset you can import this asset from any other asset, so you can import images from html, css, js, ts, ...
+
+## Parcel image transformer
+
+Using the Parcel transformer `@parcel/transformer-image` you can resize, change the format and quality of an image. To do this we added the possibility to define query parameters.
+
+To do these image transformations we rely on the image transformation library [Sharp](https://sharp.pixelplumbing.com/), therefore we require you to install it locally using `npm install sharp -D` or `yarn install sharp -D`.
+
+The query parameters you can use are:
+
+- `width`: The width to resize the image to
+- `height`: The height to resize the image to
+- `quality`: The image quality percentage you want, for example `?quality=75`
+- `as`: File format to use, for example: `?as=webp`
+
+Supported image formats: `jpeg` / `jpg`, `png`, `webp`, `tiff`, `heic` / `heif` and `raw`
+
+A JavaScript example:
+
+{% sample %}
+{% samplefile "main.js" %}
+
+```js
+import imageUrl from "url:./image.jpeg?as=webp&width=250";
+```
+
+{% endsamplefile %}
+{% endsample %}
+
+An HTML example:
+
+{% sample %}
+{% samplefile "index.html" %}
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>HTML Example</title>
+  </head>
+  <body>
+    <picture>
+      <source src="url:./image.jpeg?as=webp&width=800" type="image/webp" />
+      <source src="url:./image.jpeg?width=800" type="image/jpeg" />
+      <img src="url:./image.jpeg?width=200" alt="test image" />
+    </picture>
+  </body>
+</html>
+```
+
+{% endsamplefile %}
+{% endsample %}
diff --git a/src/recipes/react.md b/src/recipes/react.md
@@ -3,7 +3,7 @@ layout: layout.njk
 eleventyNavigation:
   key: recipes-react
   title: <img src="/assets/lang-icons/react.svg" alt=""/> React
-  order: 6
+  order: 3
 ---
 
 Compared to Webpack, Parcel's paradigm is to use your HTML file as the entry point, not merely the main script: