@docusaurus/types 3.5.2 → 3.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/types",
-  "version": "3.5.2",
+  "version": "3.6.0",
   "description": "Common types for Docusaurus packages.",
   "types": "./src/index.d.ts",
   "publishConfig": {
@@ -20,12 +20,12 @@
     "joi": "^17.9.2",
     "react-helmet-async": "^1.3.0",
     "utility-types": "^3.10.0",
-    "webpack": "^5.88.1",
+    "webpack": "^5.95.0",
     "webpack-merge": "^5.9.0"
   },
   "peerDependencies": {
     "react": "^18.0.0",
     "react-dom": "^18.0.0"
   },
-  "gitHead": "eeec303dd773774ed5a023884800da0b061f6942"
+  "gitHead": "05bba6d4f495ef6b0bec5d41453932bb97981830"
 }

package/src/bundler.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type webpack from 'webpack';
+
+// We use Webpack and Rspack interchangeably because most Rspack APIs are
+// compatible with Webpack. So it's ok to use Webpack types for Rspack too.
+// When compatibility doesn't work, use "CurrentBundler.name"
+// See https://github.com/facebook/docusaurus/pull/10402
+export type CurrentBundler = {
+  name: 'webpack' | 'rspack';
+  instance: typeof webpack;
+};

package/src/config.d.ts

@@ -7,7 +7,7 @@
 
 import type {SiteStorage} from './context';
 import type {RuleSetRule} from 'webpack';
-import type {Required as RequireKeys, DeepPartial} from 'utility-types';
+import type {DeepPartial, Overwrite} from 'utility-types';
 import type {I18nConfig} from './i18n';
 import type {PluginConfig, PresetConfig, HtmlTagObject} from './plugin';
 
@@ -123,7 +123,18 @@ export type StorageConfig = {
   namespace: boolean | string;
 };
 
+export type FasterConfig = {
+  swcJsLoader: boolean;
+  swcJsMinimizer: boolean;
+  swcHtmlMinimizer: boolean;
+  lightningCssMinimizer: boolean;
+  mdxCrossCompilerCache: boolean;
+  rspackBundler: boolean;
+};
+
 export type FutureConfig = {
+  experimental_faster: FasterConfig;
+
   experimental_storage: StorageConfig;
 
   /**
@@ -392,6 +403,7 @@ export type DocusaurusConfig = {
    *
    * @see https://docusaurus.io/docs/api/docusaurus-config#ssrTemplate
    */
+  // TODO Docusaurus v4 - rename to ssgTemplate?
   ssrTemplate?: string;
   /**
    * Will be used as title delimiter in the generated `<title>` tag.
@@ -416,6 +428,9 @@ export type DocusaurusConfig = {
      * Babel loader and preset; otherwise, you can provide your custom Webpack
      * rule set.
      */
+    // TODO Docusaurus v4
+    //  Use an object type ({isServer}) so that it conforms to jsLoaderFactory
+    //  Eventually deprecate this if swc loader becomes stable?
     jsLoader: 'babel' | ((isServer: boolean) => RuleSetRule);
   };
   /** Markdown-related options. */
@@ -423,11 +438,21 @@ export type DocusaurusConfig = {
 };
 
 /**
- * Docusaurus config, as provided by the user (partial/unnormalized). This type
+ * Docusaurus config, as provided by the user (partial/un-normalized). This type
  * is used to provide type-safety / IDE auto-complete on the config file.
  * @see https://docusaurus.io/docs/typescript-support
  */
-export type Config = RequireKeys<
+export type Config = Overwrite<
   DeepPartial<DocusaurusConfig>,
-  'title' | 'url' | 'baseUrl'
+  {
+    title: DocusaurusConfig['title'];
+    url: DocusaurusConfig['url'];
+    baseUrl: DocusaurusConfig['baseUrl'];
+    future?: Overwrite<
+      DeepPartial<FutureConfig>,
+      {
+        experimental_faster?: boolean | FasterConfig;
+      }
+    >;
+  }
 >;

package/src/context.d.ts

@@ -8,6 +8,7 @@ import type {DocusaurusConfig} from './config';
 import type {CodeTranslations, I18n} from './i18n';
 import type {LoadedPlugin, PluginVersionInformation} from './plugin';
 import type {PluginRouteConfig} from './routing';
+import type {CurrentBundler} from './bundler';
 
 export type DocusaurusContext = {
   siteConfig: DocusaurusConfig;
@@ -74,6 +75,11 @@ export type LoadContext = {
    * Defines the default browser storage behavior for a site
    */
   siteStorage: SiteStorage;
+
+  /**
+   * The bundler used to build the site (Webpack or Rspack)
+   */
+  currentBundler: CurrentBundler;
 };
 
 export type Props = LoadContext & {

package/src/index.d.ts

@@ -14,6 +14,7 @@ export {
   ParseFrontMatter,
   DocusaurusConfig,
   FutureConfig,
+  FasterConfig,
   StorageConfig,
   Config,
 } from './config';
@@ -72,6 +73,8 @@ export {
   HtmlTags,
 } from './plugin';
 
+export {CurrentBundler} from './bundler';
+
 export {
   RouteConfig,
   PluginRouteConfig,

package/src/plugin.d.ts

@@ -15,6 +15,7 @@ import type {ThemeConfig} from './config';
 import type {LoadContext, Props} from './context';
 import type {SwizzleConfig} from './swizzle';
 import type {RouteConfig} from './routing';
+import type {CurrentBundler} from './bundler';
 
 export type PluginOptions = {id?: string} & {[key: string]: unknown};
 
@@ -54,13 +55,16 @@ export type PluginContentLoadedActions = {
 };
 
 export type ConfigureWebpackUtils = {
+  currentBundler: CurrentBundler;
   getStyleLoaders: (
     isServer: boolean,
     cssOptions: {[key: string]: unknown},
   ) => RuleSetRule[];
   getJSLoader: (options: {
     isServer: boolean;
-    babelOptions?: {[key: string]: unknown};
+    // TODO Docusaurus v4 remove?
+    //  not ideal because JS Loader might not use Babel...
+    babelOptions?: string | {[key: string]: unknown};
   }) => RuleSetRule;
 };
 
@@ -122,12 +126,13 @@ export type Plugin<Content = unknown> = {
       head: {[location: string]: HelmetServerState};
     },
   ) => Promise<void> | void;
-  // TODO refactor the configureWebpack API surface: use an object instead of
-  // multiple params (requires breaking change)
+  // TODO Docusaurus v4 ?
+  //  refactor the configureWebpack API surface: use an object instead of
+  //  multiple params (requires breaking change)
   configureWebpack?: (
     config: WebpackConfiguration,
     isServer: boolean,
-    utils: ConfigureWebpackUtils,
+    configureWebpackUtils: ConfigureWebpackUtils,
     content: Content,
   ) => WebpackConfiguration & {
     mergeStrategy?: {
@@ -191,9 +196,8 @@ export type LoadedPlugin = InitializedPlugin & {
 export type PluginModule<Content = unknown> = {
   (context: LoadContext, options: unknown):
     | Plugin<Content>
-    | Promise<Plugin<Content>>
     | null
-    | Promise<null>;
+    | Promise<Plugin<Content> | null>;
 
   validateOptions?: <T, U>(data: OptionValidationContext<T, U>) => U;
   validateThemeConfig?: <T>(data: ThemeConfigValidationContext<T>) => T;