feat(core): support TypeScript + ESM configuration (#9317)

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>

packages/create-docusaurus/src/index.ts

@@ -157,17 +157,6 @@ async function copyTemplate(
 ): Promise<void> {
   await fs.copy(path.join(templatesDir, 'shared'), dest);
 
-  // TypeScript variants will copy duplicate resources like CSS & config from
-  // base template
-  if (typescript) {
-    await fs.copy(template.path, dest, {
-      filter: async (filePath) =>
-        (await fs.stat(filePath)).isDirectory() ||
-        path.extname(filePath) === '.css' ||
-        path.basename(filePath) === 'docusaurus.config.js',
-    });
-  }
-
   await fs.copy(typescript ? template.tsVariantPath! : template.path, dest, {
     // Symlinks don't exist in published npm packages anymore, so this is only
     // to prevent errors during local testing

packages/create-docusaurus/templates/classic-typescript/docusaurus.config.ts

@@ -0,0 +1,133 @@
+import {themes as prismThemes} from 'prism-react-renderer';
+import type {Config} from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const config: Config = {
+  title: 'My Site',
+  tagline: 'Dinosaurs are cool',
+  favicon: 'img/favicon.ico',
+
+  // Set the production url of your site here
+  url: 'https://your-docusaurus-site.example.com',
+  // Set the /<baseUrl>/ pathname under which your site is served
+  // For GitHub pages deployment, it is often '/<projectName>/'
+  baseUrl: '/',
+
+  // GitHub pages deployment config.
+  // If you aren't using GitHub pages, you don't need these.
+  organizationName: 'facebook', // Usually your GitHub org/user name.
+  projectName: 'docusaurus', // Usually your repo name.
+
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+
+  // Even if you don't use internationalization, you can use this field to set
+  // useful metadata like html lang. For example, if your site is Chinese, you
+  // may want to replace "en" with "zh-Hans".
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          sidebarPath: './sidebars.ts',
+          // Please change this to your repo.
+          // Remove this to remove the "edit this page" links.
+          editUrl:
+            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
+        },
+        blog: {
+          showReadingTime: true,
+          // Please change this to your repo.
+          // Remove this to remove the "edit this page" links.
+          editUrl:
+            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
+        },
+        theme: {
+          customCss: './src/css/custom.css',
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  themeConfig: {
+    // Replace with your project's social card
+    image: 'img/docusaurus-social-card.jpg',
+    navbar: {
+      title: 'My Site',
+      logo: {
+        alt: 'My Site Logo',
+        src: 'img/logo.svg',
+      },
+      items: [
+        {
+          type: 'docSidebar',
+          sidebarId: 'tutorialSidebar',
+          position: 'left',
+          label: 'Tutorial',
+        },
+        {to: '/blog', label: 'Blog', position: 'left'},
+        {
+          href: 'https://github.com/facebook/docusaurus',
+          label: 'GitHub',
+          position: 'right',
+        },
+      ],
+    },
+    footer: {
+      style: 'dark',
+      links: [
+        {
+          title: 'Docs',
+          items: [
+            {
+              label: 'Tutorial',
+              to: '/docs/intro',
+            },
+          ],
+        },
+        {
+          title: 'Community',
+          items: [
+            {
+              label: 'Stack Overflow',
+              href: 'https://stackoverflow.com/questions/tagged/docusaurus',
+            },
+            {
+              label: 'Discord',
+              href: 'https://discordapp.com/invite/docusaurus',
+            },
+            {
+              label: 'Twitter',
+              href: 'https://twitter.com/docusaurus',
+            },
+          ],
+        },
+        {
+          title: 'More',
+          items: [
+            {
+              label: 'Blog',
+              to: '/blog',
+            },
+            {
+              label: 'GitHub',
+              href: 'https://github.com/facebook/docusaurus',
+            },
+          ],
+        },
+      ],
+      copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;

packages/create-docusaurus/templates/classic-typescript/package.json

@@ -26,6 +26,7 @@
   "devDependencies": {
     "@docusaurus/module-type-aliases": "3.0.0-beta.0",
     "@docusaurus/tsconfig": "3.0.0-beta.0",
+    "@docusaurus/types": "3.0.0-beta.0",
     "typescript": "~5.2.2"
   },
   "browserslist": {

packages/create-docusaurus/templates/classic-typescript/sidebars.ts

@@ -0,0 +1,31 @@
+import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+
+/**
+ * Creating a sidebar enables you to:
+ - create an ordered group of docs
+ - render a sidebar for each doc of that group
+ - provide next/previous navigation
+
+ The sidebars can be generated from the filesystem, or explicitly defined here.
+
+ Create as many sidebars as you want.
+ */
+const sidebars: SidebarsConfig = {
+  // By default, Docusaurus generates a sidebar from the docs folder structure
+  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
+
+  // But you can create a sidebar manually
+  /*
+  tutorialSidebar: [
+    'intro',
+    'hello',
+    {
+      type: 'category',
+      label: 'Tutorial',
+      items: ['tutorial-basics/create-a-document'],
+    },
+  ],
+   */
+};
+
+export default sidebars;

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

@@ -4,10 +4,7 @@
 // There are various equivalent ways to declare your Docusaurus config.
 // See: https://docusaurus.io/docs/api/docusaurus-config
 
-const {themes} = require('prism-react-renderer');
-
-const lightCodeTheme = themes.github;
-const darkCodeTheme = themes.dracula;
+import {themes as prismThemes} from 'prism-react-renderer';
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
@@ -43,7 +40,7 @@ const config = {
       /** @type {import('@docusaurus/preset-classic').Options} */
       ({
         docs: {
-          sidebarPath: require.resolve('./sidebars.js'),
+          sidebarPath: './sidebars.js',
           // Please change this to your repo.
           // Remove this to remove the "edit this page" links.
           editUrl:
@@ -57,7 +54,7 @@ const config = {
             'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
         },
         theme: {
-          customCss: require.resolve('./src/css/custom.css'),
+          customCss: './src/css/custom.css',
         },
       }),
     ],
@@ -135,10 +132,10 @@ const config = {
         copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
       },
       prism: {
-        theme: lightCodeTheme,
-        darkTheme: darkCodeTheme,
+        theme: prismThemes.github,
+        darkTheme: prismThemes.dracula,
       },
     }),
 };
 
-module.exports = config;
+export default config;

packages/create-docusaurus/templates/classic/package.json

@@ -23,7 +23,8 @@
     "react-dom": "^18.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.0.0-beta.0"
+    "@docusaurus/module-type-aliases": "3.0.0-beta.0",
+    "@docusaurus/types": "3.0.0-beta.0"
   },
   "browserslist": {
     "production": [

packages/create-docusaurus/templates/shared/sidebars.js → packages/create-docusaurus/templates/classic/sidebars.js

@@ -30,4 +30,4 @@ const sidebars = {
    */
 };
 
-module.exports = sidebars;
+export default sidebars;

packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-document.md

@@ -42,7 +42,7 @@ This is my **first Docusaurus document**!
 It is also possible to create your sidebar explicitly in `sidebars.js`:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   tutorialSidebar: [
     'intro',
     // highlight-next-line

packages/create-docusaurus/templates/shared/docs/tutorial-extras/manage-docs-versions.md

@@ -28,7 +28,7 @@ To navigate seamlessly across versions, add a version dropdown.
 Modify the `docusaurus.config.js` file:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       items: [

packages/create-docusaurus/templates/shared/docs/tutorial-extras/translate-your-site.md

@@ -11,7 +11,7 @@ Let's translate `docs/intro.md` to French.
 Modify `docusaurus.config.js` to add support for the `fr` locale:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   i18n: {
     defaultLocale: 'en',
     locales: ['en', 'fr'],
@@ -54,7 +54,7 @@ To navigate seamlessly across languages, add a locale dropdown.
 Modify the `docusaurus.config.js` file:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       items: [

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

@@ -45,7 +45,6 @@
     "@types/react-router-config": "^5.0.7",
     "combine-promises": "^1.1.0",
     "fs-extra": "^11.1.1",
-    "import-fresh": "^3.3.0",
     "js-yaml": "^4.1.0",
     "lodash": "^4.17.21",
     "tslib": "^2.6.0",

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

@@ -17,7 +17,7 @@ import {
   readVersionsFile,
 } from './versions/files';
 import {validateVersionName} from './versions/validation';
-import {loadSidebarsFileUnsafe} from './sidebars';
+import {loadSidebarsFile} from './sidebars';
 import {CURRENT_VERSION_NAME} from './constants';
 import type {PluginOptions} from '@docusaurus/plugin-content-docs';
 import type {LoadContext} from '@docusaurus/types';
@@ -37,7 +37,7 @@ async function createVersionedSidebarFile({
   // Note: we don't need the sidebars file to be normalized: it's ok to let
   // plugin option changes to impact older, versioned sidebars
   // We don't validate here, assuming the user has already built the version
-  const sidebars = await loadSidebarsFileUnsafe(sidebarPath);
+  const sidebars = await loadSidebarsFile(sidebarPath);
 
   // Do not create a useless versioned sidebars file if sidebars file is empty
   // or sidebars are disabled/false)

packages/docusaurus-plugin-content-docs/src/sidebars/index.ts

@@ -9,10 +9,9 @@ import fs from 'fs-extra';
 import path from 'path';
 import _ from 'lodash';
 import logger from '@docusaurus/logger';
-import {Globby} from '@docusaurus/utils';
+import {loadFreshModule, Globby} from '@docusaurus/utils';
 import Yaml from 'js-yaml';
 import combinePromises from 'combine-promises';
-import importFresh from 'import-fresh';
 import {validateSidebars, validateCategoryMetadataFile} from './validation';
 import {normalizeSidebars} from './normalization';
 import {processSidebars} from './processor';
@@ -68,7 +67,7 @@ async function readCategoriesMetadata(contentPath: string) {
   );
 }
 
-export async function loadSidebarsFileUnsafe(
+async function loadSidebarsFileUnsafe(
   sidebarFilePath: string | false | undefined,
 ): Promise<SidebarsConfig> {
   // false => no sidebars
@@ -89,7 +88,19 @@ export async function loadSidebarsFileUnsafe(
   }
 
   // We don't want sidebars to be cached because of hot reloading.
-  return importFresh(sidebarFilePath);
+  const module = await loadFreshModule(sidebarFilePath);
+
+  // TODO unsafe, need to refactor and improve validation
+  return module as SidebarsConfig;
+}
+
+export async function loadSidebarsFile(
+  sidebarFilePath: string | false | undefined,
+): Promise<SidebarsConfig> {
+  const sidebars = await loadSidebarsFileUnsafe(sidebarFilePath);
+
+  // TODO unsafe, need to refactor and improve validation
+  return sidebars as SidebarsConfig;
 }
 
 export async function loadSidebars(

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

@@ -47,6 +47,8 @@ declare module '@docusaurus/plugin-ideal-image' {
      */
     disableInDev?: boolean;
   };
+
+  export type Options = Partial<PluginOptions>;
 }
 
 declare module '@theme/IdealImage' {

packages/docusaurus-types/src/index.d.ts

@@ -52,6 +52,7 @@ export {
   PluginVersionInformation,
   Preset,
   PresetConfig,
+  PresetConfigDefined,
   PresetModule,
   OptionValidationContext,
   ThemeConfigValidationContext,

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

@@ -26,11 +26,9 @@ export type PluginConfig =
   | false
   | null;
 
-export type PresetConfig =
-  | string
-  | [string, {[key: string]: unknown}]
-  | false
-  | null;
+export type PresetConfigDefined = string | [string, {[key: string]: unknown}];
+
+export type PresetConfig = PresetConfigDefined | false | null;
 
 /**
  * - `type: 'package'`, plugin is in a different package.