docs: precompress array rules and social media crawlers (#502)

peterpeterparker · github-actions[bot] · web-flow · commit d1b9ecd12dd8 · 2025-08-26T14:23:06.000+02:00
* docs: precompress array rules and social media crawlers

Signed-off-by: David Dal Busco &lt;david.dalbusco@outlook.com&gt;

* 📄 Update LLMs.txt snapshot for PR review

---------

Signed-off-by: David Dal Busco &lt;david.dalbusco@outlook.com&gt;
Co-authored-by: github-actions &lt;41898282+github-actions[bot]@users.noreply.github.com&gt;
diff --git a/.llms-snapshots/llms-full.txt b/.llms-snapshots/llms-full.txt
@@ -1804,7 +1804,7 @@ This `source` attribute works similarly to Git's `.gitignore`, and you can speci
 
 ### GZIP
 
-When deploying your application, the CLI automatically searches for JavaScript (js), ES Module (mjs), CSS (css) and HTML (html) files in the `source` folder to optimize them using Gzip compression. This improves the performance of your app when it is served on the web.
+When deploying your application, the CLI automatically searches for files matching the pattern `**/*.+(css|js|mjs|html)` in the `source` folder to optimize them using Gzip compression. This improves the performance of your app when it is served on the web.
 
 By default, precompression stores **both** the original and compressed versions in Storage.
 
@@ -1814,7 +1814,7 @@ You can disable it entirely or customize which files are precompressed, whether
 
 If you change the precompress configuration and your project has already been deployed, run `juno clear` before redeploying to ensure you change is applied.
 
-## Disable precompression
+#### Disable precompression
 
 Set the `precompress` option to `false` in your configuration:
 
@@ -1824,7 +1824,7 @@ juno.config.js
 import { defineConfig } from "@junobuild/config";export default defineConfig({  satellite: {    ids: {      production: "qsgjb-riaaa-aaaaa-aaaga-cai"    },    source: "dist",    precompress: false  }});
 ```
 
-## Customize the file matching pattern
+#### Customize the file matching pattern
 
 If you want to customize the default pattern `**/*.+(css|js|mjs|html)` to better suit your needs, you can specify your own pattern. For example:
 
@@ -1834,20 +1834,26 @@ juno.config.js
 import { defineConfig } from "@junobuild/config";export default defineConfig({  satellite: {    ids: {      production: "qsgjb-riaaa-aaaaa-aaaga-cai"    },    source: "dist",    precompress: {      pattern: "**/*.jpg" // precompress JPEG files only    }  }});
 ```
 
-## Decide what happens to original files
+#### Decide what happens to original files
 
 The `mode` option controls what happens to the original files after compression:
 
 *   `"both"` — upload both the original and the compressed version. _(default)_
 *   `"replace"` — upload only the compressed version and serve it with the appropriate `Content-Encoding` header.
 
+**Warning:**
+
+If you use `replace` for HTML, some social media crawlers (e.g. Twitter, LinkedIn) may not be able to fetch your pages correctly, resulting in missing or broken social previews.
+
+To avoid this, instead of providing a single precompression rule, it's recommended to fine-tune the behavior using an **array of rules** (([see below](#use-multiple-rules))).
+
 juno.config.js
 
 ```
 import { defineConfig } from "@junobuild/config";export default defineConfig({  satellite: {    ids: {      production: "qsgjb-riaaa-aaaaa-aaaga-cai"    },    source: "dist",    precompress: {      mode: "replace"    }  }});
 ```
 
-## Choose the compression algorithm
+#### Choose the compression algorithm
 
 By default, precompression uses **Gzip** (`algorithm: "gzip"`) because it offers a good balance between compression speed, compatibility, and size.
 
@@ -1859,6 +1865,18 @@ juno.config.js
 import { defineConfig } from "@junobuild/config";export default defineConfig({  satellite: {    ids: {      production: "qsgjb-riaaa-aaaaa-aaaga-cai"    },    source: "dist",    precompress: {      algorithm: "brotli"    }  }});
 ```
 
+#### Use multiple rules
+
+In some cases, particularly when using `mode: replace`, you may want to apply different precompression strategies depending on the file type. For example, using replace for JavaScript and CSS files, but doing so for HTML can break social media previews.
+
+To handle this, the precompress option also accepts an array of rules:
+
+juno.config.js
+
+```
+import { defineConfig } from "@junobuild/config";export default defineConfig({  satellite: {    ids: {      production: "qsgjb-riaaa-aaaaa-aaaga-cai"    },    source: "dist",    precompress: [      {        pattern: "**/*.+(js|mjs|css)",        algorithm: "brotli",        mode: "replace"      },      {        pattern: "**/*.html",        algorithm: "brotli",        mode: "both"      }    ]  }});
+```
+
 ### Encoding types
 
 When deploying, the CLI automatically maps the encoding type based on the file extension. The encoding information is then used in the satellite to provide the appropriate HTTP response header `Content-Encoding`.
@@ -7724,7 +7742,7 @@ Usage: juno functions publish [options]Options:  --no-apply            Submit th
 Upgrade your serverless functions.
 
 ```
-Usage: juno functions upgrade [options]Options:  --cdn                 Select a previously published WASM file from the CDN (interactive).  --cdn-path            Use a specific published WASM file from the CDN.  --clear-chunks        Clear any previously uploaded WASM chunks (applies if the WASM size is greater than 2MB).  --no-snapshot         Skip creating a snapshot before upgrading.  -r, --reset           Reset to the initial state.  -s, --src             A path to a specific local gzipped WASM file to publish.  -h, --help            Output usage information.Notes:- If no option is provided, the default local build output will be used.- If --src is specified, it takes precedence over any CDN options.- Use --cdn to interactively select from recent published releases.
+Usage: juno functions upgrade [options]Options:  --cdn                 Select a previously published WASM file from the CDN (interactive).  --cdn-path            Use a specific published WASM file from the CDN.  -s, --src             A path to a specific local gzipped WASM file to publish.  --clear-chunks        Clear any previously uploaded WASM chunks (applies if the WASM size is greater than 2MB).  --no-snapshot         Skip creating a snapshot before upgrading.  -r, --reset           Reset to the initial state.  -m, --mode            Choose which environment to use (production, staging, development). Defaults to production if omitted.  -p, --profile         Specify an optional profile to use (e.g. personal, team). Useful when managing multiple Mission Controls.  --container-url       Override a custom container URL. If not provided, defaults to production or the local container in development mode.  --console-url         Specify a custom URL to access the developer Console.  -h, --help            Output usage information.Notes:- If no option is provided, the default local build output will be used.- If --src is specified, it takes precedence over any CDN options.- Use --cdn to interactively select from recent published releases.
 ```
 
 ---
@@ -7905,7 +7923,7 @@ import { defineConfig } from "@junobuild/config";export default defineConfig({
 
 ### Precompress
 
-When deploying your application, the CLI automatically searches for JavaScript (js), ES Module (mjs), CSS (css) and HTML (html) files in the `source` folder to optimize them using Gzip compression. This improves the performance of your app when it is served on the web.
+When deploying your application, the CLI automatically searches for files matching the pattern `**/*.+(css|js|mjs|html)` in the `source` folder to optimize them using Gzip compression. This improves the performance of your app when it is served on the web.
 
 By default, precompression stores **both** the original and compressed versions in Storage.
 
@@ -7915,7 +7933,7 @@ You can disable it entirely or customize which files are precompressed, whether
 
 If you change the precompress configuration and your project has already been deployed, run `juno clear` before redeploying to ensure you change is applied.
 
-## Disable precompression
+#### Disable precompression
 
 Set the `precompress` option to `false` in your configuration:
 
@@ -7925,7 +7943,7 @@ juno.config.js
 import { defineConfig } from "@junobuild/config";export default defineConfig({  satellite: {    ids: {      production: "qsgjb-riaaa-aaaaa-aaaga-cai"    },    source: "dist",    precompress: false  }});
 ```
 
-## Customize the file matching pattern
+#### Customize the file matching pattern
 
 If you want to customize the default pattern `**/*.+(css|js|mjs|html)` to better suit your needs, you can specify your own pattern. For example:
 
@@ -7935,20 +7953,26 @@ juno.config.js
 import { defineConfig } from "@junobuild/config";export default defineConfig({  satellite: {    ids: {      production: "qsgjb-riaaa-aaaaa-aaaga-cai"    },    source: "dist",    precompress: {      pattern: "**/*.jpg" // precompress JPEG files only    }  }});
 ```
 
-## Decide what happens to original files
+#### Decide what happens to original files
 
 The `mode` option controls what happens to the original files after compression:
 
 *   `"both"` — upload both the original and the compressed version. _(default)_
 *   `"replace"` — upload only the compressed version and serve it with the appropriate `Content-Encoding` header.
 
+**Warning:**
+
+If you use `replace` for HTML, some social media crawlers (e.g. Twitter, LinkedIn) may not be able to fetch your pages correctly, resulting in missing or broken social previews.
+
+To avoid this, instead of providing a single precompression rule, it's recommended to fine-tune the behavior using an **array of rules** (([see below](#use-multiple-rules))).
+
 juno.config.js
 
 ```
 import { defineConfig } from "@junobuild/config";export default defineConfig({  satellite: {    ids: {      production: "qsgjb-riaaa-aaaaa-aaaga-cai"    },    source: "dist",    precompress: {      mode: "replace"    }  }});
 ```
 
-## Choose the compression algorithm
+#### Choose the compression algorithm
 
 By default, precompression uses **Gzip** (`algorithm: "gzip"`) because it offers a good balance between compression speed, compatibility, and size.
 
@@ -7960,6 +7984,18 @@ juno.config.js
 import { defineConfig } from "@junobuild/config";export default defineConfig({  satellite: {    ids: {      production: "qsgjb-riaaa-aaaaa-aaaga-cai"    },    source: "dist",    precompress: {      algorithm: "brotli"    }  }});
 ```
 
+#### Use multiple rules
+
+In some cases, particularly when using `mode: replace`, you may want to apply different precompression strategies depending on the file type. For example, using replace for JavaScript and CSS files, but doing so for HTML can break social media previews.
+
+To handle this, the precompress option also accepts an array of rules:
+
+juno.config.js
+
+```
+import { defineConfig } from "@junobuild/config";export default defineConfig({  satellite: {    ids: {      production: "qsgjb-riaaa-aaaaa-aaaga-cai"    },    source: "dist",    precompress: [      {        pattern: "**/*.+(js|mjs|css)",        algorithm: "brotli",        mode: "replace"      },      {        pattern: "**/*.html",        algorithm: "brotli",        mode: "both"      }    ]  }});
+```
+
 ### Encoding
 
 When deploying, the CLI automatically maps the encoding type based on the file extension. The encoding information is then used in the satellite to provide the appropriate HTTP response header `Content-Encoding`.
diff --git a/docs/build/components/precompress.mdx b/docs/build/components/precompress.mdx
@@ -1,4 +1,4 @@
-When deploying your application, the CLI automatically searches for JavaScript (js), ES Module (mjs), CSS (css) and HTML (html) files in the `source` folder to optimize them using Gzip compression. This improves the performance of your app when it is served on the web.
+When deploying your application, the CLI automatically searches for files matching the pattern `**/*.+(css|js|mjs|html)` in the `source` folder to optimize them using Gzip compression. This improves the performance of your app when it is served on the web.
 
 By default, precompression stores **both** the original and compressed versions in Storage.
 
@@ -10,7 +10,7 @@ If you change the precompress configuration and your project has already been de
 
 :::
 
-## Disable precompression
+#### Disable precompression
 
 Set the `precompress` option to `false` in your configuration:
 
@@ -28,7 +28,7 @@ export default defineConfig({
 });
 ```
 
-## Customize the file matching pattern
+#### Customize the file matching pattern
 
 If you want to customize the default pattern `**/*.+(css|js|mjs|html)` to better suit your needs, you can specify your own pattern. For example:
 
@@ -48,13 +48,21 @@ export default defineConfig({
 });
 ```
 
-## Decide what happens to original files
+#### Decide what happens to original files
 
 The `mode` option controls what happens to the original files after compression:
 
 - `"both"` — upload both the original and the compressed version. _(default)_
 - `"replace"` — upload only the compressed version and serve it with the appropriate `Content-Encoding` header.
 
+:::warning
+
+If you use `replace` for HTML, some social media crawlers (e.g. Twitter, LinkedIn) may not be able to fetch your pages correctly, resulting in missing or broken social previews.
+
+To avoid this, instead of providing a single precompression rule, it's recommended to fine-tune the behavior using an **array of rules** ([see below](#use-multiple-rules)).
+
+:::
+
 ```javascript title="juno.config.js"
 import { defineConfig } from "@junobuild/config";
 
@@ -71,7 +79,7 @@ export default defineConfig({
 });
 ```
 
-## Choose the compression algorithm
+#### Choose the compression algorithm
 
 By default, precompression uses **Gzip** (`algorithm: "gzip"`) because it offers a good balance between compression speed, compatibility, and size.
 
@@ -92,3 +100,34 @@ export default defineConfig({
   }
 });
 ```
+
+#### Use multiple rules
+
+In some cases, particularly when using `mode: replace`, you may want to apply different precompression strategies depending on the file type. For example, using replace for JavaScript and CSS files, but doing so for HTML can break social media previews.
+
+To handle this, the precompress option also accepts an array of rules:
+
+```javascript title="juno.config.js"
+import { defineConfig } from "@junobuild/config";
+
+export default defineConfig({
+  satellite: {
+    ids: {
+      production: "qsgjb-riaaa-aaaaa-aaaga-cai"
+    },
+    source: "dist",
+    precompress: [
+      {
+        pattern: "**/*.+(js|mjs|css)",
+        algorithm: "brotli",
+        mode: "replace"
+      },
+      {
+        pattern: "**/*.html",
+        algorithm: "brotli",
+        mode: "both"
+      }
+    ]
+  }
+});
+```
