feat: TypeScript presets/plugins should expose Options typing (#5456)

* each TS plugin should export option types + preset export option / themeConfig types + remove TS typechecking for the bootstrap theme

* each TS plugin should export option types + preset export option / themeConfig types + remove TS typechecking for the bootstrap theme

* fix remaining TS errors

* fix remaining TS errors

* TS fix

* Add JSDoc type annotations to init templates and TS docs

* missing title char

packages/docusaurus-init/templates/classic/docusaurus.config.js

@@ -1,8 +1,9 @@
 const lightCodeTheme = require('prism-react-renderer/themes/github');
 const darkCodeTheme = require('prism-react-renderer/themes/dracula');
 
+// With JSDoc @type annotations, IDEs can provide config autocompletion
 /** @type {import('@docusaurus/types').DocusaurusConfig} */
-module.exports = {
+(module.exports = {
   title: 'My Site',
   tagline: 'Dinosaurs are cool',
   url: 'https://your-docusaurus-test-site.com',
@@ -12,7 +13,33 @@ module.exports = {
   favicon: 'img/favicon.ico',
   organizationName: 'facebook', // Usually your GitHub org/user name.
   projectName: 'docusaurus', // Usually your repo name.
-  themeConfig: {
+
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      /** @type {import('@docusaurus/preset-classic').Options} */
+      ({
+        docs: {
+          sidebarPath: require.resolve('./sidebars.js'),
+          // Please change this to your repo.
+          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
+        },
+        blog: {
+          showReadingTime: true,
+          // Please change this to your repo.
+          editUrl:
+            'https://github.com/facebook/docusaurus/edit/main/website/blog/',
+        },
+        theme: {
+          customCss: require.resolve('./src/css/custom.css'),
+        },
+      }),
+    ],
+  ],
+
+  themeConfig:
+    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+    ({
       navbar: {
         title: 'My Site',
         logo: {
@@ -83,26 +110,5 @@ module.exports = {
         theme: lightCodeTheme,
         darkTheme: darkCodeTheme,
       },
-  },
+    }),
-  presets: [
+});
-    [
-      '@docusaurus/preset-classic',
-      {
-        docs: {
-          sidebarPath: require.resolve('./sidebars.js'),
-          // Please change this to your repo.
-          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
-        },
-        blog: {
-          showReadingTime: true,
-          // Please change this to your repo.
-          editUrl:
-            'https://github.com/facebook/docusaurus/edit/main/website/blog/',
-        },
-        theme: {
-          customCss: require.resolve('./src/css/custom.css'),
-        },
-      },
-    ],
-  ],
-};

packages/docusaurus-init/templates/facebook/docusaurus.config.js

@@ -7,8 +7,9 @@
  * @format
  */
 
+// With JSDoc @type annotations, IDEs can provide config autocompletion
 /** @type {import('@docusaurus/types').DocusaurusConfig} */
-module.exports = {
+(module.exports = {
   title: 'My Site',
   tagline: 'The tagline of my site',
   url: 'https://your-docusaurus-test-site.com',
@@ -18,7 +19,33 @@ module.exports = {
   favicon: 'img/favicon.ico',
   organizationName: 'facebook', // Usually your GitHub org/user name.
   projectName: 'docusaurus', // Usually your repo name.
-  themeConfig: {
+
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      /** @type {import('@docusaurus/preset-classic').Options} */
+      ({
+        docs: {
+          sidebarPath: require.resolve('./sidebars.js'),
+          // Please change this to your repo.
+          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
+        },
+        blog: {
+          showReadingTime: true,
+          // Please change this to your repo.
+          editUrl:
+            'https://github.com/facebook/docusaurus/edit/main/website/blog/',
+        },
+        theme: {
+          customCss: require.resolve('./src/css/custom.css'),
+        },
+      }),
+    ],
+  ],
+
+  themeConfig:
+    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+    ({
       navbar: {
         title: 'My Facebook Project',
         logo: {
@@ -118,26 +145,5 @@ module.exports = {
         // Please do not remove the credits, help to publicize Docusaurus :)
         copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc. Built with Docusaurus.`,
       },
-  },
+    }),
-  presets: [
+});
-    [
-      '@docusaurus/preset-classic',
-      {
-        docs: {
-          sidebarPath: require.resolve('./sidebars.js'),
-          // Please change this to your repo.
-          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
-        },
-        blog: {
-          showReadingTime: true,
-          // Please change this to your repo.
-          editUrl:
-            'https://github.com/facebook/docusaurus/edit/main/website/blog/',
-        },
-        theme: {
-          customCss: require.resolve('./src/css/custom.css'),
-        },
-      },
-    ],
-  ],
-};

packages/docusaurus-plugin-client-redirects/package.json

@@ -3,6 +3,7 @@
   "version": "2.0.0-beta.5",
   "description": "Client redirects plugin for Docusaurus.",
   "main": "lib/index.js",
+  "types": "src/plugin-client-redirects.d.ts",
   "scripts": {
     "build": "tsc",
     "watch": "tsc --watch"

packages/docusaurus-plugin-client-redirects/src/plugin-client-redirects.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+
+export type Options = import('./types').UserPluginOptions;

packages/docusaurus-plugin-content-blog/package.json

@@ -3,7 +3,7 @@
   "version": "2.0.0-beta.5",
   "description": "Blog plugin for Docusaurus.",
   "main": "lib/index.js",
-  "types": "index.d.ts",
+  "types": "src/plugin-content-blog.d.ts",
   "scripts": {
     "build": "tsc",
     "watch": "tsc --watch"

packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts

@@ -5,6 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+declare module '@docusaurus/plugin-content-blog' {
+  export type Options = import('./types').PluginOptions;
+}
+
 declare module '@theme/BlogSidebar' {
   export type BlogSidebarItem = {title: string; permalink: string};
   export type BlogSidebar = {
@@ -24,8 +28,8 @@ declare module '@theme/BlogPostPage' {
   import type {BlogSidebar} from '@theme/BlogSidebar';
   import type {TOCItem} from '@docusaurus/types';
 
-  export type FrontMatter = import('./src/blogFrontMatter').BlogPostFrontMatter;
+  export type FrontMatter = import('./blogFrontMatter').BlogPostFrontMatter;
-  export type Assets = import('./src/types').Assets;
+  export type Assets = import('./types').Assets;
 
   export type Metadata = {
     readonly title: string;
@@ -38,7 +42,7 @@ declare module '@theme/BlogPostPage' {
     readonly truncated?: string;
     readonly nextItem?: {readonly title: string; readonly permalink: string};
     readonly prevItem?: {readonly title: string; readonly permalink: string};
-    readonly authors: import('./src/types').Author[];
+    readonly authors: import('./types').Author[];
     readonly tags: readonly {
       readonly label: string;
       readonly permalink: string;
@@ -122,4 +126,7 @@ declare module '@theme/BlogTagsPostsPage' {
     readonly metadata: Tag;
     readonly items: readonly {readonly content: Content}[];
   };
+
+  const BlogTagsPostsPage: (props: Props) => JSX.Element;
+  export default BlogTagsPostsPage;
 }

packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts

@@ -5,6 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+declare module '@docusaurus/plugin-content-docs' {
+  export type Options = import('./types').PluginOptions;
+}
+
+// TODO public api surface types should rather be exposed as "@docusaurus/plugin-content-docs"
 declare module '@docusaurus/plugin-content-docs-types' {
   type VersionBanner = import('./types').VersionBanner;
   type GlobalDataVersion = import('./types').GlobalVersion;

packages/docusaurus-plugin-content-pages/src/plugin-content-pages.d.ts

@@ -5,6 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+declare module '@docusaurus/plugin-content-pages' {
+  export type Options = import('./types').PluginOptions;
+}
+
 declare module '@theme/MDXPage' {
   import type {TOCItem} from '@docusaurus/types';
 

packages/docusaurus-plugin-content-pages/types.d.ts

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+// TODO legacy, this does not seem like a good place to add those TS types!
 declare module 'remark-admonitions' {
   type Options = Record<string, unknown>;
 

packages/docusaurus-plugin-sitemap/package.json

@@ -3,6 +3,7 @@
   "version": "2.0.0-beta.5",
   "description": "Simple sitemap generation plugin for Docusaurus.",
   "main": "lib/index.js",
+  "types": "src/plugin-sitemap.d.ts",
   "scripts": {
     "build": "tsc",
     "watch": "tsc --watch"

packages/docusaurus-plugin-sitemap/src/plugin-sitemap.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+
+export type Options = import('./types').PluginOptions;

packages/docusaurus-preset-classic/package.json

@@ -3,6 +3,7 @@
   "version": "2.0.0-beta.5",
   "description": "Classic preset for Docusaurus.",
   "main": "src/index.js",
+  "types": "src/preset-classic.d.ts",
   "publishConfig": {
     "access": "public"
   },

packages/docusaurus-preset-classic/src/index.js

@@ -6,7 +6,7 @@
  */
 
 module.exports = function preset(context, opts = {}) {
-  const {siteConfig = {}} = context;
+  const {siteConfig} = context;
   const {themeConfig} = siteConfig;
   const {algolia, googleAnalytics, gtag} = themeConfig;
   const isProd = process.env.NODE_ENV === 'production';

packages/docusaurus-preset-classic/src/preset-classic.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+
+export type Options = {
+  debug?: boolean;
+  docs?: false | import('@docusaurus/plugin-content-docs').Options;
+  blog?: false | import('@docusaurus/plugin-content-blog').Options;
+  pages?: false | import('@docusaurus/plugin-content-pages').Options;
+  sitemap?: false | import('@docusaurus/plugin-sitemap').Options;
+  theme?: import('@docusaurus/theme-classic').Options;
+};
+
+export type ThemeConfig = import('@docusaurus/theme-common').ThemeConfig & {
+  // Those themeConfigs should rather be moved to preset/plugin options
+  // Plugin data can be made available to browser thank to the globalData api
+  algolia?: unknown; // TODO type plugin
+  googleAnalytics?: unknown; // TODO type plugin
+  gtag?: unknown; // TODO type plugin
+};

packages/docusaurus-theme-bootstrap/package.json

@@ -31,7 +31,7 @@
     "@docusaurus/module-type-aliases": "2.0.0-beta.5"
   },
   "scripts": {
-    "build": "tsc --noEmit && yarn babel && yarn prettier",
+    "build": "yarn babel && yarn prettier",
     "watch": "yarn babel --watch",
     "babel": "babel src -d lib --extensions \".tsx,.ts\" --ignore \"**/*.d.ts\" --copy-files",
     "prettier": "prettier --config ../../.prettierrc --ignore-path ../../.prettierignore --write \"**/*.{js,ts}\""

packages/docusaurus-theme-classic/src/index.ts

@@ -89,7 +89,7 @@ function getInfimaCSSFile(direction) {
   }.css`;
 }
 
-type PluginOptions = {
+export type PluginOptions = {
   customCss?: string;
 };
 

packages/docusaurus-theme-classic/src/theme/BlogTagsPostsPage/index.tsx

@@ -32,7 +32,7 @@ function useBlogPostsPlural() {
     );
 }
 
-function BlogTagsPostPage(props: Props): JSX.Element {
+export default function BlogTagsPostsPage(props: Props): JSX.Element {
   const {metadata, items, sidebar} = props;
   const {allTagsPath, name: tagName, count} = metadata;
   const blogPostsPlural = useBlogPostsPlural();
@@ -80,5 +80,3 @@ function BlogTagsPostPage(props: Props): JSX.Element {
     </BlogLayout>
   );
 }
-
-export default BlogTagsPostPage;

packages/docusaurus-theme-classic/src/theme/MDXComponents/index.tsx

@@ -51,7 +51,7 @@ const MDXComponents: MDXComponentsObject = {
 
     // See comment for `code` above
     if (isValidElement(children) && isValidElement(children?.props?.children)) {
-      return children?.props.children;
+      return children.props.children;
     }
 
     return (

packages/docusaurus-theme-classic/src/types.d.ts

@@ -12,6 +12,10 @@
 /// <reference types="@docusaurus/plugin-content-docs" />
 /// <reference types="@docusaurus/plugin-content-pages" />
 
+declare module '@docusaurus/theme-classic' {
+  export type Options = import('./index').PluginOptions;
+}
+
 declare module '@theme/AnnouncementBar' {
   const AnnouncementBar: () => JSX.Element | null;
   export default AnnouncementBar;

website/_dogfooding/dogfooding.config.js

@@ -4,7 +4,8 @@ const path = require('path');
 exports.dogfoodingPluginInstances = [
   [
     '@docusaurus/plugin-content-docs',
-    {
+    /** @type {import('@docusaurus/plugin-content-docs').Options} */
+    ({
       id: 'docs-tests',
       routeBasePath: '/tests/docs',
       sidebarPath: '_dogfooding/docs-tests-sidebars.js',
@@ -12,12 +13,13 @@ exports.dogfoodingPluginInstances = [
       // Using a symlinked folder as source, test for use-case https://github.com/facebook/docusaurus/issues/3272
       // The target folder uses a _ prefix to test against an edge case regarding MDX partials: https://github.com/facebook/docusaurus/discussions/5181#discussioncomment-1018079
       path: fs.realpathSync('_dogfooding/docs-tests-symlink'),
-    },
+    }),
   ],
 
   [
     '@docusaurus/plugin-content-blog',
-    {
+    /** @type {import('@docusaurus/plugin-content-blog').Options} */
+    ({
       id: 'blog-tests',
       path: '_dogfooding/_blog tests',
       routeBasePath: '/tests/blog',
@@ -28,15 +30,16 @@ exports.dogfoodingPluginInstances = [
         type: 'all',
         copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
       },
-    },
+    }),
   ],
 
   [
     '@docusaurus/plugin-content-pages',
-    {
+    /** @type {import('@docusaurus/plugin-content-pages').Options} */
+    ({
       id: 'pages-tests',
       path: '_dogfooding/_pages tests',
       routeBasePath: '/tests/pages',
-    },
+    }),
   ],
 ];

website/docs/typescript-support.md

@@ -42,7 +42,7 @@ It is **not possible** to use a TypeScript config file in Docusaurus, unless you
 
 We recommend using [JSDoc type annotations](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html):
 
-```js title="docusaurus.config.js
+```js title="docusaurus.config.js"
 // highlight-start
 /** @type {import('@docusaurus/types').Plugin} */
 // highlight-end
@@ -55,15 +55,49 @@ function MyPlugin(context, options) {
 // highlight-start
 /** @type {import('@docusaurus/types').DocusaurusConfig} */
 // highlight-end
-const config = {
+(module.exports = {
   title: 'Docusaurus',
   tagline: 'Build optimized websites quickly, focus on your content',
   organizationName: 'facebook',
   projectName: 'docusaurus',
   plugins: [MyPlugin],
-};
+  presets: [
-
+    [
-module.exports = config;
+      '@docusaurus/preset-classic',
+      // highlight-start
+      /** @type {import('@docusaurus/preset-classic').Options} */
+      // highlight-end
+      ({
+        docs: {
+          path: 'docs',
+          sidebarPath: 'sidebars.js',
+        },
+        blog: {
+          path: 'blog',
+          postsPerPage: 5,
+        },
+      }),
+    ],
+  ],
+  themeConfig:
+    // highlight-start
+    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+    // highlight-end
+    ({
+      colorMode: {
+        defaultMode: 'dark',
+      },
+      navbar: {
+        hideOnScroll: true,
+        title: 'Docusaurus',
+        logo: {
+          alt: 'Docusaurus Logo',
+          src: 'img/docusaurus.svg',
+          srcDark: 'img/docusaurus_keytar.svg',
+        },
+      },
+    }),
+});
 ```
 
 :::tip

website/docusaurus.config.js

@@ -38,7 +38,6 @@ const isDeployPreview =
   process.env.NETLIFY && process.env.CONTEXT === 'deploy-preview';
 
 const baseUrl = process.env.BASE_URL || '/';
-const isBootstrapPreset = process.env.DOCUSAURUS_PRESET === 'bootstrap';
 
 // Special deployment for staging locales until they get enough translations
 // https://app.netlify.com/sites/docusaurus-i18n-staging
@@ -105,7 +104,8 @@ const TwitterSvg =
     require('./src/featureRequests/FeatureRequestsPlugin'),
     [
       '@docusaurus/plugin-content-docs',
-      {
+      /** @type {import('@docusaurus/plugin-content-docs').Options} */
+      ({
         id: 'community',
         path: 'community',
         routeBasePath: 'community',
@@ -119,11 +119,12 @@ const TwitterSvg =
         sidebarPath: require.resolve('./sidebarsCommunity.js'),
         showLastUpdateAuthor: true,
         showLastUpdateTime: true,
-      },
+      }),
     ],
     [
       '@docusaurus/plugin-client-redirects',
-      {
+      /** @type {import('@docusaurus/plugin-client-redirects').Options} */
+      ({
         fromExtensions: ['html'],
         createRedirects: function (path) {
           // redirect to /docs from /docs/introduction,
@@ -146,7 +147,7 @@ const TwitterSvg =
             to: '/community/resources',
           },
         ],
-      },
+      }),
     ],
     [
       '@docusaurus/plugin-ideal-image',
@@ -222,10 +223,9 @@ const TwitterSvg =
   ],
   presets: [
     [
-      isBootstrapPreset
+      '@docusaurus/preset-classic',
-        ? '@docusaurus/preset-bootstrap'
+      /** @type {import('@docusaurus/preset-classic').Options} */
-        : '@docusaurus/preset-classic',
+      ({
-      {
         debug: true, // force debug plugin usage
         docs: {
           // routeBasePath: '/',
@@ -284,10 +284,13 @@ const TwitterSvg =
         theme: {
           customCss: [require.resolve('./src/css/custom.css')],
         },
-      },
+      }),
     ],
   ],
-  themeConfig: {
+
+  themeConfig:
+    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+    ({
       liveCodeBlock: {
         playgroundPosition: 'bottom',
       },
@@ -482,5 +485,5 @@ const TwitterSvg =
         },
         copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc. Built with Docusaurus.`,
       },
-  },
+    }),
 });

website/package.json

@@ -14,8 +14,6 @@
     "write-heading-ids": "docusaurus write-heading-ids",
     "start:baseUrl": "cross-env BASE_URL='/build/' yarn start",
     "build:baseUrl": "cross-env BASE_URL='/build/' yarn build",
-    "start:bootstrap": "cross-env DOCUSAURUS_PRESET=bootstrap yarn start",
-    "build:bootstrap": "cross-env DOCUSAURUS_PRESET=bootstrap yarn build",
     "start:blogOnly": "cross-env yarn start --config=docusaurus.config-blog-only.js",
     "build:blogOnly": "cross-env yarn build --config=docusaurus.config-blog-only.js",
     "netlify:build:production": "yarn docusaurus write-translations && yarn netlify:crowdin:delay && yarn netlify:crowdin:uploadSources && yarn netlify:crowdin:downloadTranslations && yarn build",