@docusaurus/plugin-client-redirects 2.0.0-beta.15d451942 → 2.0.0-beta.16

package/src/collectRedirects.ts

@@ -5,40 +5,67 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {flatten, uniqBy, difference, groupBy} from 'lodash';
-import {
-  PluginContext,
-  RedirectMetadata,
+import _ from 'lodash';
+import type {
   PluginOptions,
   RedirectOption,
-} from './types';
+} from '@docusaurus/plugin-client-redirects';
+import type {PluginContext, RedirectMetadata} from './types';
 import {
   createFromExtensionsRedirects,
   createToExtensionsRedirects,
 } from './extensionRedirects';
 import {validateRedirect} from './redirectValidation';
+import {
+  applyTrailingSlash,
+  type ApplyTrailingSlashParams,
+} from '@docusaurus/utils-common';
 
-import chalk from 'chalk';
+import logger from '@docusaurus/logger';
 
 export default function collectRedirects(
   pluginContext: PluginContext,
+  trailingSlash: boolean | undefined,
 ): RedirectMetadata[] {
-  const redirects = doCollectRedirects(pluginContext);
+  let redirects = doCollectRedirects(pluginContext);
+
+  redirects = applyRedirectsTrailingSlash(redirects, {
+    trailingSlash,
+    baseUrl: pluginContext.baseUrl,
+  });
+
   validateCollectedRedirects(redirects, pluginContext);
   return filterUnwantedRedirects(redirects, pluginContext);
 }
 
+// If users wants to redirect to=/abc and they enable trailingSlash=true then
+// => we don't want to reject the to=/abc (as only /abc/ is an existing/valid
+// path now)
+// => we want to redirect to=/abc/ without the user having to change all its
+// redirect plugin options
+// It should be easy to toggle siteConfig.trailingSlash option without having to
+// change other configs
+function applyRedirectsTrailingSlash(
+  redirects: RedirectMetadata[],
+  params: ApplyTrailingSlashParams,
+) {
+  return redirects.map((redirect) => ({
+    ...redirect,
+    to: applyTrailingSlash(redirect.to, params),
+  }));
+}
+
 function validateCollectedRedirects(
   redirects: RedirectMetadata[],
   pluginContext: PluginContext,
 ) {
-  const redirectValidationErrors: string[] = redirects
+  const redirectValidationErrors = redirects
     .map((redirect) => {
       try {
         validateRedirect(redirect);
         return undefined;
-      } catch (e) {
-        return e.message;
+      } catch (err) {
+        return (err as Error).message;
       }
     })
     .filter(Boolean);
@@ -52,7 +79,7 @@ function validateCollectedRedirects(
 
   const allowedToPaths = pluginContext.relativeRoutesPaths;
   const toPaths = redirects.map((redirect) => redirect.to);
-  const illegalToPaths = difference(toPaths, allowedToPaths);
+  const illegalToPaths = _.difference(toPaths, allowedToPaths);
   if (illegalToPaths.length > 0) {
     throw new Error(
       `You are trying to create client-side redirections to paths that do not exist:
@@ -71,34 +98,26 @@ function filterUnwantedRedirects(
 ): RedirectMetadata[] {
   // we don't want to create twice the same redirect
   // that would lead to writing twice the same html redirection file
-  Object.entries(groupBy(redirects, (redirect) => redirect.from)).forEach(
+  Object.entries(_.groupBy(redirects, (redirect) => redirect.from)).forEach(
     ([from, groupedFromRedirects]) => {
       if (groupedFromRedirects.length > 1) {
-        console.error(
-          chalk.red(
-            `@docusaurus/plugin-client-redirects: multiple redirects are created with the same "from" pathname=${from}
-It is not possible to redirect the same pathname to multiple destinations:
-- ${groupedFromRedirects.map((r) => JSON.stringify(r)).join('\n- ')}
-`,
-          ),
-        );
+        logger.error`name=${'@docusaurus/plugin-client-redirects'}: multiple redirects are created with the same "from" pathname: path=${from}
+It is not possible to redirect the same pathname to multiple destinations: ${groupedFromRedirects.map(
+          (r) => JSON.stringify(r),
+        )}`;
       }
     },
   );
-  const collectedRedirects = uniqBy(redirects, (redirect) => redirect.from);
+  const collectedRedirects = _.uniqBy(redirects, (redirect) => redirect.from);
 
   // We don't want to override an already existing route with a redirect file!
   const redirectsOverridingExistingPath = collectedRedirects.filter(
     (redirect) => pluginContext.relativeRoutesPaths.includes(redirect.from),
   );
   if (redirectsOverridingExistingPath.length > 0) {
-    console.error(
-      chalk.red(
-        `@docusaurus/plugin-client-redirects: some redirects would override existing paths, and will be ignored:
-- ${redirectsOverridingExistingPath.map((r) => JSON.stringify(r)).join('\n- ')}
-`,
-      ),
-    );
+    logger.error`name=${'@docusaurus/plugin-client-redirects'}: some redirects would override existing paths, and will be ignored: ${redirectsOverridingExistingPath.map(
+      (r) => JSON.stringify(r),
+    )}`;
   }
   return collectedRedirects.filter(
     (redirect) => !pluginContext.relativeRoutesPaths.includes(redirect.from),
@@ -127,7 +146,7 @@ function doCollectRedirects(pluginContext: PluginContext): RedirectMetadata[] {
 function createRedirectsOptionRedirects(
   redirectsOption: PluginOptions['redirects'],
 ): RedirectMetadata[] {
-  // For conveniency, user can use a string or a string[]
+  // For convenience, user can use a string or a string[]
   function optionToRedirects(option: RedirectOption): RedirectMetadata[] {
     if (typeof option.from === 'string') {
       return [{from: option.from, to: option.to}];
@@ -138,7 +157,7 @@ function createRedirectsOptionRedirects(
     }));
   }
 
-  return flatten(redirectsOption.map(optionToRedirects));
+  return redirectsOption.flatMap(optionToRedirects);
 }
 
 // Create redirects from the "createRedirects" fn provided by the user
@@ -154,13 +173,11 @@ function createCreateRedirectsOptionRedirects(
     const froms: string[] =
       typeof fromsMixed === 'string' ? [fromsMixed] : fromsMixed;
 
-    return froms.map((from) => {
-      return {
-        from,
-        to: path,
-      };
-    });
+    return froms.map((from) => ({
+      from,
+      to: path,
+    }));
   }
 
-  return flatten(paths.map(createPathRedirects));
+  return paths.flatMap(createPathRedirects);
 }

package/src/createRedirectPageContent.ts

@@ -7,15 +7,15 @@
 
 import * as eta from 'eta';
 import redirectPageTemplate from './templates/redirectPage.template.html';
-import {memoize} from 'lodash';
+import _ from 'lodash';
 
 type CreateRedirectPageOptions = {
   toUrl: string;
 };
 
-const getCompiledRedirectPageTemplate = memoize(() => {
-  return eta.compile(redirectPageTemplate.trim());
-});
+const getCompiledRedirectPageTemplate = _.memoize(() =>
+  eta.compile(redirectPageTemplate.trim()),
+);
 
 function renderRedirectPageTemplate(data: Record<string, unknown>) {
   const compiled = getCompiledRedirectPageTemplate();

package/src/extensionRedirects.ts

@@ -5,34 +5,35 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {flatten} from 'lodash';
-import {removeSuffix} from '@docusaurus/utils';
-import {RedirectMetadata} from './types';
+import {
+  addTrailingSlash,
+  removeSuffix,
+  removeTrailingSlash,
+} from '@docusaurus/utils';
+import type {RedirectMetadata} from './types';
 
 const ExtensionAdditionalMessage =
-  "If the redirect extension system is not good enough for your usecase, you can create redirects yourself with the 'createRedirects' plugin option.";
+  'If the redirect extension system is not good enough for your use case, you can create redirects yourself with the "createRedirects" plugin option.';
 
 const validateExtension = (ext: string) => {
   if (!ext) {
     throw new Error(
-      `Extension=['${String(
-        ext,
-      )}'] is not allowed. ${ExtensionAdditionalMessage}`,
+      `Extension "${ext}" is not allowed.\n${ExtensionAdditionalMessage}`,
     );
   }
   if (ext.includes('.')) {
     throw new Error(
-      `Extension=['${ext}'] contains a . (dot) and is not allowed. ${ExtensionAdditionalMessage}`,
+      `Extension "${ext}" contains a "." (dot) which is not allowed.\n${ExtensionAdditionalMessage}`,
     );
   }
   if (ext.includes('/')) {
     throw new Error(
-      `Extension=['${ext}'] contains a / and is not allowed. ${ExtensionAdditionalMessage}`,
+      `Extension "${ext}" contains a "/" (slash) which is not allowed.\n${ExtensionAdditionalMessage}`,
     );
   }
   if (encodeURIComponent(ext) !== ext) {
     throw new Error(
-      `Extension=['${ext}'] contains invalid uri characters. ${ExtensionAdditionalMessage}`,
+      `Extension "${ext}" contains invalid URI characters.\n${ExtensionAdditionalMessage}`,
     );
   }
 };
@@ -60,10 +61,11 @@ export function createToExtensionsRedirects(
     return [];
   };
 
-  return flatten(paths.map(createPathRedirects));
+  return paths.flatMap(createPathRedirects);
 }
 
-// Create new /path.html that redirects to existing an /path
+// Create new /path.html/index.html that redirects to existing an /path
+// The filename pattern might look weird but it's on purpose (see https://github.com/facebook/docusaurus/issues/5055)
 export function createFromExtensionsRedirects(
   paths: string[],
   extensions: string[],
@@ -76,14 +78,18 @@ export function createFromExtensionsRedirects(
     dottedExtensions.some((ext) => str.endsWith(ext));
 
   const createPathRedirects = (path: string): RedirectMetadata[] => {
-    if (path === '' || path.endsWith('/') || alreadyEndsWithAnExtension(path)) {
+    if (path === '' || path === '/' || alreadyEndsWithAnExtension(path)) {
       return [];
     }
     return extensions.map((ext) => ({
-      from: `${path}.${ext}`,
+      // /path => /path.html
+      // /path/ => /path.html/
+      from: path.endsWith('/')
+        ? addTrailingSlash(`${removeTrailingSlash(path)}.${ext}`)
+        : `${path}.${ext}`,
       to: path,
     }));
   };
 
-  return flatten(paths.map(createPathRedirects));
+  return paths.flatMap(createPathRedirects);
 }

package/src/index.ts

@@ -5,21 +5,24 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {LoadContext, Plugin, Props} from '@docusaurus/types';
-import {UserPluginOptions, PluginContext, RedirectMetadata} from './types';
+import type {LoadContext, Plugin, Props} from '@docusaurus/types';
+import type {PluginContext, RedirectMetadata} from './types';
+import type {PluginOptions} from '@docusaurus/plugin-client-redirects';
 
 import normalizePluginOptions from './normalizePluginOptions';
 import collectRedirects from './collectRedirects';
 import writeRedirectFiles, {
   toRedirectFilesMetadata,
-  RedirectFileMetadata,
+  type RedirectFileMetadata,
 } from './writeRedirectFiles';
 import {removePrefix, addLeadingSlash} from '@docusaurus/utils';
 
 export default function pluginClientRedirectsPages(
-  _context: LoadContext,
-  opts: UserPluginOptions,
+  context: LoadContext,
+  opts: PluginOptions,
 ): Plugin<unknown> {
+  const {trailingSlash} = context.siteConfig;
+
   const options = normalizePluginOptions(opts);
 
   return {
@@ -34,11 +37,15 @@ export default function pluginClientRedirectsPages(
         options,
       };
 
-      const redirects: RedirectMetadata[] = collectRedirects(pluginContext);
+      const redirects: RedirectMetadata[] = collectRedirects(
+        pluginContext,
+        trailingSlash,
+      );
 
       const redirectFiles: RedirectFileMetadata[] = toRedirectFilesMetadata(
         redirects,
         pluginContext,
+        trailingSlash,
       );
 
       // Write files only at the end: make code more easy to test without IO

package/src/normalizePluginOptions.ts

@@ -5,9 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {PluginOptions, RedirectOption, UserPluginOptions} from './types';
+import type {
+  PluginOptions,
+  Options as UserPluginOptions,
+  RedirectOption,
+} from '@docusaurus/plugin-client-redirects';
 import {Joi, PathnameSchema} from '@docusaurus/utils-validation';
-import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
+import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
 
 export const DefaultPluginOptions: PluginOptions = {
   id: DEFAULT_PLUGIN_ID, // TODO temporary

package/src/plugin-client-redirects.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 RedirectOption = {
+  to: string;
+  from: string | string[];
+};
+
+// For a given existing route path,
+// return all the paths from which we should redirect from
+export type CreateRedirectsFnOption = (
+  path: string,
+) => string[] | string | null | undefined;
+
+export type PluginOptions = {
+  id: string;
+  fromExtensions: string[];
+  toExtensions: string[];
+  redirects: RedirectOption[];
+  createRedirects?: CreateRedirectsFnOption;
+};
+
+export type Options = Partial<PluginOptions>;

package/src/redirectValidation.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {RedirectMetadata} from './types';
+import type {RedirectMetadata} from './types';
 import {Joi, PathnameSchema} from '@docusaurus/utils-validation';
 
 const RedirectSchema = Joi.object<RedirectMetadata>({

package/src/types.ts

@@ -5,28 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {Props} from '@docusaurus/types';
-
-export type PluginOptions = {
-  id: string;
-  fromExtensions: string[];
-  toExtensions: string[];
-  redirects: RedirectOption[];
-  createRedirects?: CreateRedirectsFnOption;
-};
-
-// For a given existing route path,
-// return all the paths from which we should redirect from
-export type CreateRedirectsFnOption = (
-  path: string,
-) => string[] | string | null | undefined;
-
-export type RedirectOption = {
-  to: string;
-  from: string | string[];
-};
-
-export type UserPluginOptions = Partial<PluginOptions>;
+import type {Props} from '@docusaurus/types';
+import type {PluginOptions} from '@docusaurus/plugin-client-redirects';
 
 // The minimal infos the plugin needs to work
 export type PluginContext = Pick<Props, 'outDir' | 'baseUrl'> & {

package/src/writeRedirectFiles.ts

@@ -7,11 +7,11 @@
 
 import fs from 'fs-extra';
 import path from 'path';
-import {memoize} from 'lodash';
+import _ from 'lodash';
 
-import {PluginContext, RedirectMetadata} from './types';
+import type {PluginContext, RedirectMetadata} from './types';
 import createRedirectPageContent from './createRedirectPageContent';
-import {getFilePathForRoutePath, normalizeUrl} from '@docusaurus/utils';
+import {normalizeUrl} from '@docusaurus/utils';
 
 export type WriteFilesPluginContext = Pick<PluginContext, 'baseUrl' | 'outDir'>;
 
@@ -24,22 +24,52 @@ export function createToUrl(baseUrl: string, to: string): string {
   return normalizeUrl([baseUrl, to]);
 }
 
+// Create redirect file path
+// Make sure this path has lower precedence over the original file path when
+// served by host providers!
+// Otherwise it can produce infinite redirect loops!
+//
+// See https://github.com/facebook/docusaurus/issues/5055
+// See https://github.com/facebook/docusaurus/pull/5085
+// See https://github.com/facebook/docusaurus/pull/5102
+function getRedirectFilePath(
+  fromPath: string,
+  trailingSlash: boolean | undefined, // Now unused, on purpose
+): string {
+  const fileName = path.basename(fromPath);
+  const filePath = path.dirname(fromPath);
+  // Edge case for https://github.com/facebook/docusaurus/pull/5102
+  // If the redirect source path is /xyz, with file /xyz.html
+  // We can't write the redirect file at /xyz.html/index.html because for Unix
+  // FS, a file/folder can't have the same name "xyz.html"
+  // The only possible solution for a redirect file is thus /xyz.html.html (I
+  // know, looks suspicious)
+  if (trailingSlash === false && fileName.endsWith('.html')) {
+    return path.join(filePath, `${fileName}.html`);
+  }
+  // If the target path is /xyz, with file /xyz/index.html, we don't want the
+  // redirect file to be /xyz.html, otherwise it would be picked in priority and
+  // the redirect file would redirect to itself. We prefer the redirect file to
+  // be /xyz.html/index.html, served with lower priority for most static hosting
+  // tools
+  return path.join(filePath, `${fileName}/index.html`);
+}
+
 export function toRedirectFilesMetadata(
   redirects: RedirectMetadata[],
   pluginContext: WriteFilesPluginContext,
+  trailingSlash: boolean | undefined,
 ): RedirectFileMetadata[] {
   // Perf: avoid rendering the template twice with the exact same "props"
   // We might create multiple redirect pages for the same destination url
   // note: the first fn arg is the cache key!
-  const createPageContentMemoized = memoize((toUrl: string) => {
-    return createRedirectPageContent({toUrl});
-  });
+  const createPageContentMemoized = _.memoize((toUrl: string) =>
+    createRedirectPageContent({toUrl}),
+  );
 
   const createFileMetadata = (redirect: RedirectMetadata) => {
-    const fileAbsolutePath = path.join(
-      pluginContext.outDir,
-      getFilePathForRoutePath(redirect.from),
-    );
+    const fileRelativePath = getRedirectFilePath(redirect.from, trailingSlash);
+    const fileAbsolutePath = path.join(pluginContext.outDir, fileRelativePath);
     const toUrl = createToUrl(pluginContext.baseUrl, redirect.to);
     const fileContent = createPageContentMemoized(toUrl);
     return {
@@ -59,7 +89,7 @@ export async function writeRedirectFile(
     // User-friendly security to prevent file overrides
     if (await fs.pathExists(file.fileAbsolutePath)) {
       throw new Error(
-        'The redirect plugin is not supposed to override existing files',
+        'The redirect plugin is not supposed to override existing files.',
       );
     }
     await fs.ensureDir(path.dirname(file.fileAbsolutePath));
@@ -72,7 +102,7 @@ export async function writeRedirectFile(
     );
   } catch (err) {
     throw new Error(
-      `Redirect file creation error for path=${file.fileAbsolutePath}: ${err}`,
+      `Redirect file creation error for "${file.fileAbsolutePath}" path: ${err}.`,
     );
   }
 }