@docusaurus/types 2.0.0-beta.fbdeefcac → 2.0.0-rc.1

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@docusaurus/types",
-  "version": "2.0.0-beta.fbdeefcac",
+  "version": "2.0.0-rc.1",
   "description": "Common types for Docusaurus packages.",
-  "main": "./src/index.js",
   "types": "./src/index.d.ts",
   "publishConfig": {
     "access": "public"
@@ -13,15 +12,19 @@
     "directory": "packages/docusaurus-types"
   },
   "license": "MIT",
-  "scripts": {
-    "test": "tsc -p ."
-  },
   "dependencies": {
+    "@types/history": "^4.7.11",
+    "@types/react": "*",
     "commander": "^5.1.0",
-    "joi": "^17.4.0",
-    "querystring": "0.2.0",
-    "webpack": "^5.40.0",
+    "joi": "^17.6.0",
+    "react-helmet-async": "^1.3.0",
+    "utility-types": "^3.10.0",
+    "webpack": "^5.73.0",
     "webpack-merge": "^5.8.0"
   },
-  "gitHead": "636c490f68d16a7452499ab722deb5ed51ef49fc"
+  "peerDependencies": {
+    "react": "^16.8.4 || ^17.0.0",
+    "react-dom": "^16.8.4 || ^17.0.0"
+  },
+  "gitHead": "c8ddd02a8e68dfaf515c20465a049a83153bd205"
 }

package/src/clientModule.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 {Location} from 'history';
+
+export type ClientModule = {
+  onRouteDidUpdate?: (args: {
+    previousLocation: Location | null;
+    location: Location;
+  }) => (() => void) | void;
+  onRouteUpdate?: (args: {
+    previousLocation: Location | null;
+    location: Location;
+  }) => (() => void) | void;
+};

package/src/config.d.ts

@@ -0,0 +1,283 @@
+/**
+ * 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 {RuleSetRule} from 'webpack';
+import type {Required as RequireKeys, DeepPartial} from 'utility-types';
+import type {I18nConfig} from './i18n';
+import type {PluginConfig, PresetConfig} from './plugin';
+
+export type ReportingSeverity = 'ignore' | 'log' | 'warn' | 'throw';
+
+export type ThemeConfig = {
+  [key: string]: unknown;
+};
+
+/**
+ * Docusaurus config, after validation/normalization.
+ */
+export type DocusaurusConfig = {
+  /**
+   * Title for your website. Will be used in metadata and as browser tab title.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#title
+   */
+  title: string;
+  /**
+   * URL for your website. This can also be considered the top-level hostname.
+   * For example, `https://facebook.github.io` is the URL of
+   * https://facebook.github.io/metro/, and `https://docusaurus.io` is the URL
+   * for https://docusaurus.io.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#url
+   */
+  url: string;
+  /**
+   * Can be considered as the path after the host. For example, `/metro/` is the
+   * base URL of https://facebook.github.io/metro/. For URLs that have no path,
+   * it should be set to `/`. Always has both leading and trailing slash.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#baseUrl
+   */
+  baseUrl: string;
+  /**
+   * Path to your site favicon; must be a URL that can be used in link's href.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#favicon
+   */
+  favicon?: string;
+  /**
+   * Allow to customize the presence/absence of a trailing slash at the end of
+   * URLs/links, and how static HTML files are generated:
+   *
+   * - `undefined` (default): keeps URLs untouched, and emit
+   *   `/docs/myDoc/index.html` for `/docs/myDoc.md`
+   * - `true`: add trailing slashes to URLs/links, and emit
+   *   `/docs/myDoc/index.html` for `/docs/myDoc.md`
+   * - `false`: remove trailing slashes from URLs/links, and emit
+   *   `/docs/myDoc.html` for `/docs/myDoc.md`
+   *
+   * @see https://github.com/slorber/trailing-slash-guide
+   * @see https://docusaurus.io/docs/api/docusaurus-config#trailingSlash
+   * @default undefined
+   */
+  trailingSlash: boolean | undefined;
+  /**
+   * The i18n configuration object to [localize your
+   * site](https://docusaurus.io/docs/i18n/introduction).
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#i18n
+   */
+  i18n: I18nConfig;
+  /**
+   * This option adds `<meta name="robots" content="noindex, nofollow">` to
+   * every page to tell search engines to avoid indexing your site.
+   *
+   * @see https://moz.com/learn/seo/robots-meta-directives
+   * @see https://docusaurus.io/docs/api/docusaurus-config#noIndex
+   * @default false
+   */
+  noIndex: boolean;
+  /**
+   * The behavior of Docusaurus when it detects any broken link.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#onBrokenLinks
+   * @default "throw"
+   */
+  onBrokenLinks: ReportingSeverity;
+  /**
+   * The behavior of Docusaurus when it detects any broken markdown link.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#onBrokenMarkdownLinks
+   * @default "warn"
+   */
+  onBrokenMarkdownLinks: ReportingSeverity;
+  /**
+   * The behavior of Docusaurus when it detects any [duplicate
+   * routes](https://docusaurus.io/docs/creating-pages#duplicate-routes).
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#onDuplicateRoutes
+   * @default "warn"
+   */
+  onDuplicateRoutes: ReportingSeverity;
+  /**
+   * The tagline for your website.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#tagline
+   * @default ""
+   */
+  tagline: string;
+  /**
+   * The GitHub user or organization that owns the repository. You don't need
+   * this if you are not using the `docusaurus deploy` command.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#organizationName
+   */
+  organizationName?: string;
+  /**
+   * The name of the GitHub repository. You don't need this if you are not using
+   * the `docusaurus deploy` command.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#projectName
+   */
+  projectName?: string;
+  /**
+   * The name of the branch to deploy the static files to. You don't need this
+   * if you are not using the `docusaurus deploy` command.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#deploymentBranch
+   */
+  deploymentBranch?: string;
+  /**
+   * The hostname of your server. Useful if you are using GitHub Enterprise. You
+   * don't need this if you are not using the `docusaurus deploy` command.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#githubHost
+   */
+  githubHost?: string;
+  /**
+   * The port of your server. Useful if you are using GitHub Enterprise. You
+   * don't need this if you are not using the `docusaurus deploy` command.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#githubPort
+   */
+  githubPort?: string;
+  /**
+   * The [theme configuration](https://docusaurus.io/docs/api/themes/configuration)
+   * object to customize your site UI like navbar and footer.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#themeConfig
+   * @default {}
+   */
+  themeConfig: ThemeConfig;
+  /**
+   * List of plugins.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#plugins
+   * @default []
+   */
+  plugins: PluginConfig[];
+  /**
+   * List of themes.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#themes
+   * @default []
+   */
+  themes: PluginConfig[];
+  /**
+   * List of presets.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#presets
+   * @default []
+   */
+  presets: PresetConfig[];
+  /**
+   * Docusaurus guards `docusaurus.config.js` from unknown fields. To add a
+   * custom field, define it on `customFields`.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#customFields
+   * @default {}
+   */
+  customFields?: {
+    [key: string]: unknown;
+  };
+  /**
+   * An array of paths, relative to the site's directory or absolute. Files
+   * under these paths will be copied to the build output as-is.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#staticDirectories
+   * @default ["static"]
+   */
+  staticDirectories: string[];
+  /**
+   * An array of scripts to load. The values can be either strings or plain
+   * objects of attribute-value maps. The `<script>` tags will be inserted in
+   * the HTML `<head>`.
+   *
+   * Note that `<script>` added here are render-blocking, so you might want to
+   * add `async: true`/`defer: true` to the objects.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#scripts
+   * @default []
+   */
+  scripts: (
+    | string
+    | {
+        src: string;
+        [key: string]: string | boolean | undefined;
+      }
+  )[];
+  /**
+   * An array of CSS sources to load. The values can be either strings or plain
+   * objects of attribute-value maps. The `<link>` tags will be inserted in the
+   * HTML `<head>`.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#stylesheets
+   * @default []
+   */
+  stylesheets: (
+    | string
+    | {
+        href: string;
+        [key: string]: string | boolean | undefined;
+      }
+  )[];
+  /**
+   * An array of [client modules](https://docusaurus.io/docs/advanced/client#client-modules)
+   * to load globally on your site.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#clientModules
+   * @default []
+   */
+  clientModules: string[];
+  /**
+   * An HTML template written in [Eta's syntax](https://eta.js.org/docs/syntax#syntax-overview)
+   * that will be used to render your application. This can be used to set
+   * custom attributes on the `body` tags, additional `meta` tags, customize the
+   * `viewport`, etc. Please note that Docusaurus will rely on the template to
+   * be correctly structured in order to function properly, once you do
+   * customize it, you will have to make sure that your template is compliant
+   * with the requirements from upstream.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#ssrTemplate
+   */
+  ssrTemplate?: string;
+  /**
+   * Will be used as title delimiter in the generated `<title>` tag.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#titleDelimiter
+   * @default "|"
+   */
+  titleDelimiter: string;
+  /**
+   * When enabled, will show a banner in case your site can't load its CSS or
+   * JavaScript files, which is a very common issue, often related to a wrong
+   * `baseUrl` in site config.
+   *
+   * @see https://docusaurus.io/docs/api/docusaurus-config#baseUrlIssueBanner
+   * @default true
+   */
+  baseUrlIssueBanner: boolean;
+  /** Webpack-related options. */
+  webpack?: {
+    /**
+     * Configuration for alternative JS loaders. "babel" will use the built-in
+     * Babel loader and preset; otherwise, you can provide your custom Webpack
+     * rule set.
+     */
+    jsLoader: 'babel' | ((isServer: boolean) => RuleSetRule);
+  };
+};
+
+/**
+ * Docusaurus config, as provided by the user (partial/unnormalized). 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<
+  DeepPartial<DocusaurusConfig>,
+  'title' | 'url' | 'baseUrl'
+>;

package/src/context.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 {DocusaurusConfig} from './config';
+import type {CodeTranslations, I18n} from './i18n';
+import type {LoadedPlugin, PluginVersionInformation} from './plugin';
+import type {RouteConfig} from './routing';
+
+export type DocusaurusContext = {
+  siteConfig: DocusaurusConfig;
+  siteMetadata: SiteMetadata;
+  globalData: GlobalData;
+  i18n: I18n;
+  codeTranslations: CodeTranslations;
+
+  // Don't put mutable values here, to avoid triggering re-renders
+  // We could reconsider that choice if context selectors are implemented
+  // isBrowser: boolean; // Not here on purpose!
+};
+
+export type SiteMetadata = {
+  readonly docusaurusVersion: string;
+  readonly siteVersion?: string;
+  readonly pluginVersions: {[pluginName: string]: PluginVersionInformation};
+};
+
+export type GlobalData = {[pluginName: string]: {[pluginId: string]: unknown}};
+
+export type LoadContext = {
+  siteDir: string;
+  generatedFilesDir: string;
+  siteConfig: DocusaurusConfig;
+  siteConfigPath: string;
+  outDir: string;
+  /**
+   * Directory where all source translations for the current locale can be found
+   * in. Constructed with `i18n.path` + `i18n.currentLocale.path` (e.g.
+   * `<siteDir>/i18n/en`)
+   */
+  localizationDir: string;
+  /**
+   * Duplicated from `siteConfig.baseUrl`, but probably worth keeping. We mutate
+   * `siteConfig` to make `baseUrl` there localized as well, but that's mostly
+   * for client-side. `context.baseUrl` is still more convenient for plugins.
+   */
+  baseUrl: string;
+  i18n: I18n;
+  codeTranslations: CodeTranslations;
+};
+
+export type Props = LoadContext & {
+  headTags: string;
+  preBodyTags: string;
+  postBodyTags: string;
+  siteMetadata: SiteMetadata;
+  routes: RouteConfig[];
+  routesPaths: string[];
+  plugins: LoadedPlugin[];
+};

package/src/i18n.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 {DeepRequired} from 'utility-types';
+
+export type I18nLocaleConfig = {
+  /** The label displayed for this locale in the locales dropdown. */
+  label: string;
+  /**
+   * BCP 47 language tag to use in `<html lang="...">` and in
+   * `<link ... hreflang="...">`
+   */
+  htmlLang: string;
+  /** Used to select the locale's CSS and html meta attribute. */
+  direction: 'ltr' | 'rtl';
+  /**
+   * The [calendar](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar)
+   * used to calculate the date era. Note that it doesn't control the actual
+   * string displayed: `MM/DD/YYYY` and `DD/MM/YYYY` are both gregory. To choose
+   * the format (`DD/MM/YYYY` or `MM/DD/YYYY`), set your locale name to `en-GB`
+   * or `en-US` (`en` means `en-US`).
+   */
+  calendar: string;
+  /**
+   * Root folder that all plugin localization folders of this locale are
+   * relative to. Will be resolved against `i18n.path`. Defaults to the locale's
+   * name.
+   */
+  path: string;
+};
+
+export type I18nConfig = {
+  /**
+   * The locale that:
+   * 1. Does not have its name in the base URL
+   * 2. Gets started with `docusaurus start` without `--locale` option
+   * 3. Will be used for the `<link hrefLang="x-default">` tag
+   */
+  defaultLocale: string;
+  /**
+   * Root folder which all locale folders are relative to. Can be absolute or
+   * relative to the config file. e.g. `i18n`
+   */
+  path: string;
+  /** List of locales deployed on your site. Must contain `defaultLocale`. */
+  locales: [string, ...string[]];
+  /** Individual options for each locale. */
+  localeConfigs: {[locale: string]: Partial<I18nLocaleConfig>};
+};
+
+export type I18n = DeepRequired<I18nConfig> & {currentLocale: string};
+
+/**
+ * Inspired by Chrome JSON, because it's a widely supported i18n format
+ * @see https://developer.chrome.com/apps/i18n-messages
+ * @see https://support.crowdin.com/file-formats/chrome-json/
+ * @see https://www.applanga.com/docs/formats/chrome_i18n_json
+ * @see https://docs.transifex.com/formats/chrome-json
+ * @see https://help.phrase.com/help/chrome-json-messages
+ */
+export type TranslationMessage = {message: string; description?: string};
+export type TranslationFileContent = {[msgId: string]: TranslationMessage};
+/**
+ * An abstract representation of how a translation file exists on disk. The core
+ * would handle the file reading/writing; plugins just need to deal with
+ * translations in-memory.
+ */
+export type TranslationFile = {
+  /**
+   * Relative to the directory where it's expected to be found. For plugin
+   * files, it's relative to `i18n/<locale>/<pluginName>/<pluginId>`. Should NOT
+   * have any extension.
+   */
+  path: string;
+  content: TranslationFileContent;
+};
+
+export type CodeTranslations = {[msgId: string]: string};

package/src/index.d.ts

@@ -5,416 +5,73 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// ESLint doesn't understand types dependencies in d.ts
-// eslint-disable-next-line import/no-extraneous-dependencies
-import type {RuleSetRule, Configuration} from 'webpack';
-import type {Command} from 'commander';
-import type {ParsedUrlQueryInput} from 'querystring';
-import type Joi from 'joi';
-
-// Convert webpack-merge webpack-merge enum to union type
-// For type retro-compatible webpack-merge upgrade: we used string literals before)
-// see https://github.com/survivejs/webpack-merge/issues/179
-type MergeStrategy = 'match' | 'merge' | 'append' | 'prepend' | 'replace';
-
-export type ReportingSeverity = 'ignore' | 'log' | 'warn' | 'error' | 'throw';
-
-export type ThemeConfig = {
-  [key: string]: unknown;
-};
-
-export interface DocusaurusConfig {
-  baseUrl: string;
-  baseUrlIssueBanner: boolean;
-  favicon?: string;
-  tagline?: string;
-  title: string;
-  url: string;
-  // trailingSlash undefined = legacy retrocompatible behavior => /file => /file/index.html
-  trailingSlash: boolean | undefined;
-  i18n: I18nConfig;
-  onBrokenLinks: ReportingSeverity;
-  onBrokenMarkdownLinks: ReportingSeverity;
-  onDuplicateRoutes: ReportingSeverity;
-  noIndex: boolean;
-  organizationName?: string;
-  projectName?: string;
-  githubHost?: string;
-  githubPort?: string;
-  plugins?: PluginConfig[];
-  themes?: PluginConfig[];
-  presets?: PresetConfig[];
-  themeConfig: ThemeConfig;
-  customFields?: {
-    [key: string]: unknown;
-  };
-  scripts?: (
-    | string
-    | {
-        src: string;
-        [key: string]: unknown;
-      }
-  )[];
-  clientModules?: string[];
-  ssrTemplate?: string;
-  stylesheets?: (
-    | string
-    | {
-        href: string;
-        [key: string]: unknown;
-      }
-  )[];
-  titleDelimiter?: string;
-  webpack?: {
-    jsLoader: 'babel' | ((isServer: boolean) => RuleSetRule);
-  };
-}
-
-/**
- * - `type: 'package'`, plugin is in a different package.
- * - `type: 'project'`, plugin is in the same docusaurus project.
- * - `type: 'local'`, none of plugin's ancestor directory contains any package.json.
- * - `type: 'synthetic'`, docusaurus generated internal plugin.
- */
-export type DocusaurusPluginVersionInformation =
-  | {
-      readonly type: 'package';
-      readonly name?: string;
-      readonly version?: string;
-    }
-  | {readonly type: 'project'}
-  | {readonly type: 'local'}
-  | {readonly type: 'synthetic'};
-
-export interface DocusaurusSiteMetadata {
-  readonly docusaurusVersion: string;
-  readonly siteVersion?: string;
-  readonly pluginVersions: Record<string, DocusaurusPluginVersionInformation>;
-}
-
-// Inspired by Chrome JSON, because it's a widely supported i18n format
-// https://developer.chrome.com/apps/i18n-messages
-// https://support.crowdin.com/file-formats/chrome-json/
-// https://www.applanga.com/docs/formats/chrome_i18n_json
-// https://docs.transifex.com/formats/chrome-json
-// https://help.phrase.com/help/chrome-json-messages
-export type TranslationMessage = {message: string; description?: string};
-export type TranslationFileContent = Record<string, TranslationMessage>;
-export type TranslationFile = {path: string; content: TranslationFileContent};
-export type TranslationFiles = TranslationFile[];
-
-export type I18nLocaleConfig = {
-  label: string;
-  direction: string;
-};
-
-export type I18nConfig = {
-  defaultLocale: string;
-  locales: [string, ...string[]];
-  localeConfigs: Record<string, Partial<I18nLocaleConfig>>;
-};
-
-export type I18n = {
-  defaultLocale: string;
-  locales: [string, ...string[]];
-  currentLocale: string;
-  localeConfigs: Record<string, I18nLocaleConfig>;
-};
-
-export interface DocusaurusContext {
-  siteConfig: DocusaurusConfig;
-  siteMetadata: DocusaurusSiteMetadata;
-  globalData: Record<string, unknown>;
-  i18n: I18n;
-  codeTranslations: Record<string, string>;
-  isClient: boolean;
-}
-
-export interface Preset {
-  plugins?: PluginConfig[];
-  themes?: PluginConfig[];
-}
-
-export type PresetConfig =
-  | [string, Record<string, unknown>]
-  | [string]
-  | string;
-
-export type HostPortCLIOptions = {
-  host?: string;
-  port?: string;
-};
-
-export type ConfigOptions = {
-  config: string;
-};
-
-export type StartCLIOptions = HostPortCLIOptions &
-  ConfigOptions & {
-    hotOnly: boolean;
-    open: boolean;
-    poll: boolean | number;
-    locale?: string;
-  };
-
-export type ServeCLIOptions = HostPortCLIOptions &
-  ConfigOptions & {
-    dir: string;
-    build: boolean;
-  };
-
-export type BuildOptions = ConfigOptions & {
-  bundleAnalyzer: boolean;
-  outDir: string;
-  minify: boolean;
-  skipBuild: boolean;
-};
-
-export type BuildCLIOptions = BuildOptions & {
-  locale?: string;
-};
-
-export interface LoadContext {
-  siteDir: string;
-  generatedFilesDir: string;
-  siteConfig: DocusaurusConfig;
-  siteConfigPath: string;
-  outDir: string;
-  baseUrl: string; // TODO to remove: useless, there's already siteConfig.baseUrl!
-  i18n: I18n;
-  ssrTemplate?: string;
-  codeTranslations: Record<string, string>;
-}
-
-export interface InjectedHtmlTags {
-  headTags: string;
-  preBodyTags: string;
-  postBodyTags: string;
-}
-
-export type HtmlTags = string | HtmlTagObject | (string | HtmlTagObject)[];
-
-export interface Props extends LoadContext, InjectedHtmlTags {
-  siteMetadata: DocusaurusSiteMetadata;
-  routes: RouteConfig[];
-  routesPaths: string[];
-  plugins: LoadedPlugin[];
-}
-
-export interface PluginContentLoadedActions {
-  addRoute(config: RouteConfig): void;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  createData(name: string, data: any): Promise<string>;
-  setGlobalData<T = unknown>(data: T): void;
-}
-
-export type AllContent = Record<
-  string, // plugin name
-  Record<
-    string, // plugin id
-    unknown // plugin data
-  >
->;
-
-// TODO improve type (not exposed by postcss-loader)
-export type PostCssOptions = Record<string, unknown> & {plugins: unknown[]};
-
-export interface Plugin<Content = unknown> {
-  name: string;
-  loadContent?(): Promise<Content>;
-  contentLoaded?({
-    content,
-    actions,
-  }: {
-    content: Content; // the content loaded by this plugin instance
-    allContent: AllContent; // content loaded by ALL the plugins
-    actions: PluginContentLoadedActions;
-  }): void;
-  routesLoaded?(routes: RouteConfig[]): void; // TODO remove soon, deprecated (alpha-60)
-  postBuild?(props: Props): void;
-  postStart?(props: Props): void;
-  // TODO refactor the configureWebpack API surface: use an object instead of multiple params (requires breaking change)
-  configureWebpack?(
-    config: Configuration,
-    isServer: boolean,
-    utils: ConfigureWebpackUtils,
-    content: Content,
-  ): Configuration & {mergeStrategy?: ConfigureWebpackFnMergeStrategy};
-  configurePostCss?(options: PostCssOptions): PostCssOptions;
-  getThemePath?(): string;
-  getTypeScriptThemePath?(): string;
-  getPathsToWatch?(): string[];
-  getClientModules?(): string[];
-  extendCli?(cli: Command): void;
-  injectHtmlTags?({
-    content: Content,
-  }): {
-    headTags?: HtmlTags;
-    preBodyTags?: HtmlTags;
-    postBodyTags?: HtmlTags;
-  };
-  // TODO before/afterDevServer implementation
-
-  // translations
-  getTranslationFiles?({
-    content,
-  }: {
-    content: Content;
-  }): Promise<TranslationFiles>;
-  getDefaultCodeTranslationMessages?(): Promise<
-    Record<
-      string, // id
-      string // message
-    >
-  >;
-  translateContent?({
-    content,
-    translationFiles,
-  }: {
-    content: Content; // the content loaded by this plugin instance
-    translationFiles: TranslationFiles;
-  }): Content;
-  translateThemeConfig?({
-    themeConfig,
-    translationFiles,
-  }: {
-    themeConfig: ThemeConfig;
-    translationFiles: TranslationFiles;
-  }): ThemeConfig;
-}
-
-export type InitializedPlugin<Content = unknown> = Plugin<Content> & {
-  readonly options: PluginOptions;
-  readonly version: DocusaurusPluginVersionInformation;
-};
-
-export type LoadedPlugin<Content = unknown> = InitializedPlugin<Content> & {
-  readonly content: Content;
-};
-
-export type PluginModule = {
-  <T, X>(context: LoadContext, options: T): Plugin<X>;
-  validateOptions?<T>(data: OptionValidationContext<T>): T;
-  validateThemeConfig?<T>(data: ThemeConfigValidationContext<T>): T;
-  getSwizzleComponentList?(): string[];
-};
-
-export type ImportedPluginModule = PluginModule & {
-  default?: PluginModule;
-};
-
-export type ConfigureWebpackFn = Plugin<unknown>['configureWebpack'];
-export type ConfigureWebpackFnMergeStrategy = Record<string, MergeStrategy>;
-export type ConfigurePostCssFn = Plugin<unknown>['configurePostCss'];
-
-export type PluginOptions = {id?: string} & Record<string, unknown>;
-
-export type PluginConfig =
-  | [string, PluginOptions]
-  | [string]
-  | string
-  | [PluginModule, PluginOptions]
-  | PluginModule;
-
-export interface ChunkRegistry {
-  loader: string;
-  modulePath: string;
-}
-
-export type Module =
-  | {
-      path: string;
-      __import?: boolean;
-      query?: ParsedUrlQueryInput;
-    }
-  | string;
-
-export interface RouteModule {
-  [module: string]: Module | RouteModule | RouteModule[];
-}
-
-export interface ChunkNames {
-  [name: string]: string | null | ChunkNames | ChunkNames[];
-}
-
-export interface RouteConfig {
-  path: string;
-  component: string;
-  modules?: RouteModule;
-  routes?: RouteConfig[];
-  exact?: boolean;
-  priority?: number;
-}
-
-// Aliases used for Webpack resolution (when using docusaurus swizzle)
-export interface ThemeAliases {
-  [alias: string]: string;
-}
-
-export interface ConfigureWebpackUtils {
-  getStyleLoaders: (
-    isServer: boolean,
-    cssOptions: {
-      [key: string]: unknown;
-    },
-  ) => RuleSetRule[];
-  getJSLoader: (options: {
-    isServer: boolean;
-    babelOptions?: Record<string, unknown>;
-  }) => RuleSetRule;
-
-  // TODO deprecated: remove before end of 2021?
-  getCacheLoader: (
-    isServer: boolean,
-    cacheOptions?: Record<string, unknown>,
-  ) => RuleSetRule | null;
-
-  // TODO deprecated: remove before end of 2021?
-  getBabelLoader: (
-    isServer: boolean,
-    options?: Record<string, unknown>,
-  ) => RuleSetRule;
-}
-
-interface HtmlTagObject {
-  /**
-   * Attributes of the html tag
-   * E.g. `{'disabled': true, 'value': 'demo', 'rel': 'preconnect'}`
-   */
-  attributes?: {
-    [attributeName: string]: string | boolean;
-  };
-  /**
-   * The tag name e.g. `div`, `script`, `link`, `meta`
-   */
-  tagName: string;
-  /**
-   * The inner HTML
-   */
-  innerHTML?: string;
-}
-
-export type ValidationResult<T> = T;
-
-export type ValidationSchema<T> = Joi.ObjectSchema<T>;
-
-export type Validate<T> = (
-  validationSchema: ValidationSchema<T>,
-  options: Partial<T>,
-) => ValidationResult<T>;
-
-export interface OptionValidationContext<T> {
-  validate: Validate<T>;
-  options: Partial<T>;
-}
-
-export interface ThemeConfigValidationContext<T> {
-  validate: Validate<T>;
-  themeConfig: Partial<T>;
-}
-
-export interface TOCItem {
-  readonly value: string;
-  readonly id: string;
-  readonly children: TOCItem[];
-}
+export {
+  ReportingSeverity,
+  ThemeConfig,
+  DocusaurusConfig,
+  Config,
+} from './config';
+
+export {
+  SiteMetadata,
+  DocusaurusContext,
+  GlobalData,
+  LoadContext,
+  Props,
+} from './context';
+
+export {ClientModule} from './clientModule';
+
+export {
+  SwizzleAction,
+  SwizzleActionStatus,
+  SwizzleConfig,
+  SwizzleComponentConfig,
+  WrapperProps,
+} from './swizzle';
+
+export {
+  I18nConfig,
+  I18nLocaleConfig,
+  I18n,
+  CodeTranslations,
+  TranslationFileContent,
+  TranslationMessage,
+  TranslationFile,
+} from './i18n';
+
+export {
+  Plugin,
+  InitializedPlugin,
+  LoadedPlugin,
+  PluginModule,
+  PluginOptions,
+  PluginConfig,
+  PluginContentLoadedActions,
+  PluginVersionInformation,
+  Preset,
+  PresetConfig,
+  PresetModule,
+  OptionValidationContext,
+  ThemeConfigValidationContext,
+  Validate,
+  ValidationSchema,
+  AllContent,
+  ConfigureWebpackUtils,
+  PostCssOptions,
+  HtmlTagObject,
+  HtmlTags,
+} from './plugin';
+
+export {
+  RouteConfig,
+  RouteContext,
+  PluginRouteContext,
+  Registry,
+  RouteChunkNames,
+  RouteModules,
+  Module,
+  ChunkNames,
+} from './routing';
+
+export {UseDataOptions} from './utils';

package/src/plugin.d.ts

@@ -0,0 +1,195 @@
+/**
+ * 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 {TranslationFile} from './i18n';
+import type {RuleSetRule, Configuration as WebpackConfiguration} from 'webpack';
+import type {CustomizeRuleString} from 'webpack-merge/dist/types';
+import type {CommanderStatic} from 'commander';
+import type Joi from 'joi';
+import type {HelmetServerState} from 'react-helmet-async';
+import type {ThemeConfig} from './config';
+import type {LoadContext, Props} from './context';
+import type {SwizzleConfig} from './swizzle';
+import type {RouteConfig} from './routing';
+
+export type PluginOptions = {id?: string} & {[key: string]: unknown};
+
+export type PluginConfig =
+  | string
+  | [string, PluginOptions]
+  | [PluginModule, PluginOptions]
+  | PluginModule
+  | false
+  | null;
+
+export type PresetConfig =
+  | string
+  | [string, {[key: string]: unknown}]
+  | false
+  | null;
+
+/**
+ * - `type: 'package'`, plugin is in a different package.
+ * - `type: 'project'`, plugin is in the same docusaurus project.
+ * - `type: 'local'`, none of the plugin's ancestor directories contains a
+ * package.json.
+ * - `type: 'synthetic'`, docusaurus generated internal plugin.
+ */
+export type PluginVersionInformation =
+  | {
+      readonly type: 'package';
+      readonly name?: string;
+      readonly version?: string;
+    }
+  | {readonly type: 'project'}
+  | {readonly type: 'local'}
+  | {readonly type: 'synthetic'};
+
+export type PluginContentLoadedActions = {
+  addRoute: (config: RouteConfig) => void;
+  createData: (name: string, data: string) => Promise<string>;
+  setGlobalData: (data: unknown) => void;
+};
+
+export type ConfigureWebpackUtils = {
+  getStyleLoaders: (
+    isServer: boolean,
+    cssOptions: {[key: string]: unknown},
+  ) => RuleSetRule[];
+  getJSLoader: (options: {
+    isServer: boolean;
+    babelOptions?: {[key: string]: unknown};
+  }) => RuleSetRule;
+};
+
+export type AllContent = {
+  [pluginName: string]: {
+    [pluginID: string]: unknown;
+  };
+};
+
+// TODO improve type (not exposed by postcss-loader)
+export type PostCssOptions = {plugins: unknown[]; [key: string]: unknown};
+
+export type ValidationSchema<T> = Joi.ObjectSchema<T>;
+
+export type Validate<In, Out> = (
+  validationSchema: ValidationSchema<Out>,
+  options: In,
+) => Out;
+
+export type OptionValidationContext<In, Out> = {
+  validate: Validate<In, Out>;
+  options: In;
+};
+
+export type ThemeConfigValidationContext<In, Out = In> = {
+  validate: Validate<In, Out>;
+  themeConfig: In;
+};
+
+export type HtmlTagObject = {
+  /**
+   * Attributes of the html tag.
+   * E.g. `{ disabled: true, value: "demo", rel: "preconnect" }`
+   */
+  attributes?: Partial<{[key: string]: string | boolean}>;
+  /** The tag name, e.g. `div`, `script`, `link`, `meta` */
+  tagName: string;
+  /** The inner HTML */
+  innerHTML?: string;
+};
+
+export type HtmlTags = string | HtmlTagObject | (string | HtmlTagObject)[];
+
+export type Plugin<Content = unknown> = {
+  name: string;
+  loadContent?: () => Promise<Content> | Content;
+  contentLoaded?: (args: {
+    /** The content loaded by this plugin instance */
+    content: Content; //
+    /** Content loaded by ALL the plugins */
+    allContent: AllContent;
+    actions: PluginContentLoadedActions;
+  }) => Promise<void> | void;
+  postBuild?: (
+    props: Props & {
+      content: Content;
+      head: {[location: string]: HelmetServerState};
+    },
+  ) => Promise<void> | void;
+  // TODO refactor the configureWebpack API surface: use an object instead of
+  // multiple params (requires breaking change)
+  configureWebpack?: (
+    config: WebpackConfiguration,
+    isServer: boolean,
+    utils: ConfigureWebpackUtils,
+    content: Content,
+  ) => WebpackConfiguration & {
+    mergeStrategy?: {
+      [key: string]: CustomizeRuleString;
+    };
+  };
+  configurePostCss?: (options: PostCssOptions) => PostCssOptions;
+  getThemePath?: () => string;
+  getTypeScriptThemePath?: () => string;
+  getPathsToWatch?: () => string[];
+  getClientModules?: () => string[];
+  extendCli?: (cli: CommanderStatic) => void;
+  injectHtmlTags?: (args: {content: Content}) => {
+    headTags?: HtmlTags;
+    preBodyTags?: HtmlTags;
+    postBodyTags?: HtmlTags;
+  };
+  // TODO before/afterDevServer implementation
+
+  // translations
+  getTranslationFiles?: (args: {
+    content: Content;
+  }) => Promise<TranslationFile[]> | TranslationFile[];
+  getDefaultCodeTranslationMessages?: () =>
+    | Promise<{[id: string]: string}>
+    | {[id: string]: string};
+  translateContent?: (args: {
+    /** The content loaded by this plugin instance. */
+    content: Content;
+    translationFiles: TranslationFile[];
+  }) => Content;
+  translateThemeConfig?: (args: {
+    themeConfig: ThemeConfig;
+    translationFiles: TranslationFile[];
+  }) => ThemeConfig;
+};
+
+export type InitializedPlugin = Plugin & {
+  readonly options: Required<PluginOptions>;
+  readonly version: PluginVersionInformation;
+  /** The absolute path to the folder containing the entry point file. */
+  readonly path: string;
+};
+
+export type LoadedPlugin = InitializedPlugin & {
+  readonly content: unknown;
+};
+
+export type PluginModule = {
+  (context: LoadContext, options: unknown): Plugin | Promise<Plugin>;
+  validateOptions?: <T, U>(data: OptionValidationContext<T, U>) => U;
+  validateThemeConfig?: <T>(data: ThemeConfigValidationContext<T>) => T;
+
+  getSwizzleComponentList?: () => string[] | undefined; // TODO deprecate this one later
+  getSwizzleConfig?: () => SwizzleConfig | undefined;
+};
+
+export type Preset = {
+  plugins?: PluginConfig[];
+  themes?: PluginConfig[];
+};
+
+export type PresetModule = {
+  (context: LoadContext, presetOptions: unknown): Preset;
+};

package/src/routing.d.ts

@@ -0,0 +1,138 @@
+/**
+ * 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 {ParsedUrlQueryInput} from 'querystring';
+
+/**
+ * A "module" represents a unit of serialized data emitted from the plugin. It
+ * will be imported on client-side and passed as props, context, etc.
+ *
+ * If it's a string, it's a file path that Webpack can `require`; if it's
+ * an object, it can also contain `query` or other metadata.
+ */
+export type Module =
+  | {
+      /**
+       * A marker that tells the route generator this is an import and not a
+       * nested object to recurse.
+       */
+      __import?: boolean;
+      path: string;
+      query?: ParsedUrlQueryInput;
+    }
+  | string;
+
+/**
+ * Represents the data attached to each route. Since the routes.js is a
+ * monolithic data file, any data (like props) should be serialized separately
+ * and registered here as file paths (a {@link Module}), so that we could
+ * code-split.
+ */
+export type RouteModules = {
+  [propName: string]: Module | RouteModules | RouteModules[];
+};
+
+/**
+ * Represents a "slice" of the final route structure returned from the plugin
+ * `addRoute` action.
+ */
+export type RouteConfig = {
+  /** With leading slash. Trailing slash will be normalized by config. */
+  path: string;
+  /** Component used to render this route, a path that Webpack can `require`. */
+  component: string;
+  /**
+   * Props. Each entry should be `[propName]: pathToPropModule` (created with
+   * `createData`)
+   */
+  modules?: RouteModules;
+  /**
+   * The route context will wrap the `component`. Use `useRouteContext` to
+   * retrieve what's declared here. Note that all custom route context declared
+   * here will be namespaced under {@link RouteContext.data}.
+   */
+  context?: RouteModules;
+  /** Nested routes config. */
+  routes?: RouteConfig[];
+  /** React router config option: `exact` routes would not match subroutes. */
+  exact?: boolean;
+  /** Used to sort routes. Higher-priority routes will be placed first. */
+  priority?: number;
+  /** Extra props; will be copied to routes.js. */
+  [propName: string]: unknown;
+};
+
+export type RouteContext = {
+  /**
+   * Plugin-specific context data.
+   */
+  data?: object | undefined;
+};
+
+/**
+ * Top-level plugin routes automatically add some context data to the route.
+ * This permits us to know which plugin is handling the current route.
+ */
+export type PluginRouteContext = RouteContext & {
+  plugin: {
+    id: string;
+    name: string;
+  };
+};
+
+/**
+ * The shape would be isomorphic to {@link RouteModules}:
+ * {@link Module} -> `string`, `RouteModules[]` -> `ChunkNames[]`.
+ *
+ * Each `string` chunk name will correlate with one key in the {@link Registry}.
+ */
+export type ChunkNames = {
+  [propName: string]: string | ChunkNames | ChunkNames[];
+};
+
+/**
+ * A map from route paths (with a hash) to the chunk names of each module, which
+ * the bundler will collect.
+ *
+ * Chunk keys are routes with a hash, because 2 routes can conflict with each
+ * other if they have the same path, e.g.: parent=/docs, child=/docs
+ *
+ * @see https://github.com/facebook/docusaurus/issues/2917
+ */
+export type RouteChunkNames = {
+  [routePathHashed: string]: ChunkNames;
+};
+
+/**
+ * Each key is the chunk name, which you can get from `routeChunkNames` (see
+ * {@link RouteChunkNames}). The values are the opts data that react-loadable
+ * needs. For example:
+ *
+ * ```js
+ * const options = {
+ *   optsLoader: {
+ *     component: () => import('./Pages.js'),
+ *     content.foo: () => import('./doc1.md'),
+ *   },
+ *   optsModules: ['./Pages.js', './doc1.md'],
+ *   optsWebpack: [
+ *     require.resolveWeak('./Pages.js'),
+ *     require.resolveWeak('./doc1.md'),
+ *   ],
+ * }
+ * ```
+ *
+ * @see https://github.com/jamiebuilds/react-loadable#declaring-which-modules-are-being-loaded
+ */
+export type Registry = {
+  readonly [chunkName: string]: [
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    Loader: () => Promise<any>,
+    ModuleName: string,
+    ResolvedModuleName: string,
+  ];
+};

package/src/swizzle.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 {JSXElementConstructor} from 'react';
+
+export type SwizzleAction = 'eject' | 'wrap';
+export type SwizzleActionStatus = 'safe' | 'unsafe' | 'forbidden';
+
+export type SwizzleComponentConfig = {
+  actions: {[action in SwizzleAction]: SwizzleActionStatus};
+  description?: string;
+};
+
+export type SwizzleConfig = {
+  components: {[componentName: string]: SwizzleComponentConfig};
+  // Other settings could be added here, like the ability to declare the config
+  // as exhaustive so that we can emit errors
+};
+
+/**
+ * This type is almost the same as `React.ComponentProps`, but with one minor
+ * fix: when the component is a function with no parameters, it produces `{}`
+ * instead of `unknown`, allowing us to spread the props derived from another
+ * component. This is useful for wrap swizzling.
+ *
+ * @see https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/60766
+ */
+export type WrapperProps<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  T extends keyof JSX.IntrinsicElements | JSXElementConstructor<any>,
+> = T extends JSXElementConstructor<infer P>
+  ? unknown extends P
+    ? // eslint-disable-next-line @typescript-eslint/ban-types
+      {}
+    : P
+  : T extends keyof JSX.IntrinsicElements
+  ? JSX.IntrinsicElements[T]
+  : // eslint-disable-next-line @typescript-eslint/ban-types
+    {};

package/src/utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 UseDataOptions = {
+  /**
+   * Throw an error, or simply return undefined if the data cannot be found. Use
+   * `true` if you are sure the data must exist.
+   */
+  failfast?: boolean;
+};

package/src/index.js

@@ -1,10 +0,0 @@
-/**
- * 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.
- */
-
-/* eslint-disable */
-'use strict';
-Object.defineProperty(exports, '__esModule', {value: true});

package/tsconfig.json

@@ -1,7 +0,0 @@
-{
-  "$schema": "http://json.schemastore.org/tsconfig",
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "noEmit": true
-  }
-}