feat(ideal-image): new option disableInDev (#6155)

* feat(ideal-image): new option disableInDev

* Add docs

* Use import type

* More docs

packages/docusaurus-plugin-ideal-image/package.json

@@ -23,6 +23,7 @@
   "dependencies": {
     "@docusaurus/core": "2.0.0-beta.14",
     "@docusaurus/lqip-loader": "2.0.0-beta.14",
+    "@docusaurus/utils-validation": "2.0.0-beta.14",
     "@docusaurus/responsive-loader": "1.5.0",
     "@endiliey/react-ideal-image": "^0.0.11",
     "react-waypoint": "^10.1.0",

packages/docusaurus-plugin-ideal-image/src/index.ts

@@ -5,13 +5,19 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {LoadContext, Plugin} from '@docusaurus/types';
+import type {
+  LoadContext,
+  Plugin,
+  OptionValidationContext,
+  ValidationResult,
+} from '@docusaurus/types';
 import type {PluginOptions} from '@docusaurus/plugin-ideal-image';
-import {Configuration} from 'webpack';
+import type {Configuration} from 'webpack';
+import {Joi} from '@docusaurus/utils-validation';
 
 import path from 'path';
 
-export default function (
+export default function pluginIdealImage(
   _context: LoadContext,
   options: PluginOptions,
 ): Plugin<void> {
@@ -19,11 +25,16 @@ export default function (
     name: 'docusaurus-plugin-ideal-image',
 
     getThemePath() {
-      return path.resolve(__dirname, './theme');
+      return path.resolve(__dirname, '../lib/theme');
+    },
+
+    getTypeScriptThemePath() {
+      return path.resolve(__dirname, '../src/theme');
     },
 
     configureWebpack(_config: Configuration, isServer: boolean) {
-      if (process.env.NODE_ENV !== 'production') {
+      const {disableInDev, ...loaderOptions} = options;
+      if (disableInDev && process.env.NODE_ENV !== 'production') {
         return {};
       }
 
@@ -44,7 +55,7 @@ export default function (
                     // eslint-disable-next-line global-require
                     adapter: require('@docusaurus/responsive-loader/sharp'),
                     name: 'assets/ideal-img/[name].[hash:hex:7].[width].[ext]',
-                    ...options,
+                    ...loaderOptions,
                   },
                 },
               ],
@@ -55,3 +66,13 @@ export default function (
     },
   };
 }
+
+export function validateOptions({
+  validate,
+  options,
+}: OptionValidationContext<PluginOptions>): ValidationResult<PluginOptions> {
+  const pluginOptionsSchema = Joi.object({
+    disableInDev: Joi.boolean().default(true),
+  }).unknown();
+  return validate(pluginOptionsSchema, options);
+}

packages/docusaurus-plugin-ideal-image/src/plugin-ideal-image.d.ts

@@ -35,6 +35,10 @@ declare module '@docusaurus/plugin-ideal-image' {
      * JPEG compression quality
      */
     quality?: number;
+    /**
+     * Just use regular images in dev mode
+     */
+    disableInDev?: boolean;
   };
 }
 

website/docs/api/plugins/plugin-ideal-image.md

@@ -5,7 +5,9 @@ title: '📦 plugin-ideal-image'
 slug: '/api/plugins/@docusaurus/plugin-ideal-image'
 ---
 
-Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder) **in the production builds**.
+import APITable from '@site/src/components/APITable';
+
+Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder).
 
 ## Installation {#installation}
 
@@ -13,18 +15,6 @@ Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, a
 npm install --save @docusaurus/plugin-ideal-image
 ```
 
-## Configuration {#configuration}
-
-Modify your `docusaurus.config.js`
-
-```js {3}
-module.exports = {
-  ...
-  plugins: ['@docusaurus/plugin-ideal-image'],
-  ...
-}
-```
-
 ## Usage {#usage}
 
 This plugin supports the PNG and JPG formats only.
@@ -40,14 +30,44 @@ import thumbnail from './path/to/img.png';
 <Image img={require('./path/to/img.png')} />
 ```
 
-## Options {#options}
+## Configuration {#configuration}
+
+Accepted fields:
+
+<APITable>
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
 | `name` | `string` | `ideal-img/[name].[hash:hex:7].[width].[ext]` | Filename template for output files. |
-| `sizes` | `array` | _original size_ | Specify all widths you want to use. If a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up). |
+| `sizes` | `number[]` | _original size_ | Specify all widths you want to use. If a specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up). |
-| `size` | `integer` | _original size_ | Specify one width you want to use; if the specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up) |
+| `size` | `number` | _original size_ | Specify one width you want to use; if the specified size exceeds the original image's width, the latter will be used (i.e. images won't be scaled up) |
-| `min` | `integer` |  | As an alternative to manually specifying `sizes`, you can specify `min`, `max` and `steps`, and the sizes will be generated for you. |
+| `min` | `number` |  | As an alternative to manually specifying `sizes`, you can specify `min`, `max` and `steps`, and the sizes will be generated for you. |
-| `max` | `integer` |  | See `min` above |
+| `max` | `number` |  | See `min` above |
-| `steps` | `integer` | `4` | Configure the number of images generated between `min` and `max` (inclusive) |
+| `steps` | `number` | `4` | Configure the number of images generated between `min` and `max` (inclusive) |
-| `quality` | `integer` | `85` | JPEG compression quality |
+| `quality` | `number` | `85` | JPEG compression quality |
+| `disableInDev` | `boolean` | `true` | You can test ideal image behavior in dev mode by setting this to `false`. **Tip**: use [network throttling](https://www.browserstack.com/guide/how-to-perform-network-throttling-in-chrome) in your browser to simulate slow networks. |
+
+</APITable>
+
+## Example configuration {#ex-config}
+
+Here's an example configuration:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-ideal-image',
+      // highlight-start
+      {
+        quality: 70,
+        max: 1030, // max resized image's size.
+        min: 640, // min resized image's size. if original is lower, use that size.
+        steps: 2, // the max number of images generated between min and max (inclusive)
+        disableInDev: false,
+      },
+      // highlight-end
+    ],
+  ],
+};
+```

website/docusaurus.config.js

@@ -178,6 +178,7 @@ const config = {
         max: 1030, // max resized image's size.
         min: 640, // min resized image's size. if original is lower, use that size.
         steps: 2, // the max number of images generated between min and max (inclusive)
+        disableInDev: false,
       },
     ],
     [