@prismicio/next 0.1.2 → 0.1.3

package/src/PrismicPreview.tsx

@@ -1,9 +1,10 @@
-import React, { useEffect } from "react";
+import * as React from "react";
+import * as prismic from "@prismicio/client";
 import { PrismicToolbar } from "@prismicio/react";
 import { useRouter } from "next/router";
 
 import { getCookie } from "./lib/getCookie";
-import { extractPreviewRefRepositoryName } from "./lib/extractPreviewRefRepositoryName";
+import { getPreviewCookieRepositoryName } from "./lib/getPreviewCookieRepositoryName";
 
 /**
  * Props for `<PrismicPreview>`.
@@ -18,33 +19,28 @@ export type PrismicPreviewProps = {
 	/**
 	 * The URL of your app's Prismic preview endpoint (default: `/api/preview`).
 	 * This URL will be fetched on preview update events.
+	 *
+	 * **Note**: If your `next.config.js` file contains a `basePath`, it is
+	 * automatically included.
 	 */
 	updatePreviewURL?: string;
 
 	/**
 	 * The URL of your app's exit preview endpoint (default: `/api/exit-preview`).
 	 * This URL will be fetched on preview exit events.
+	 *
+	 * **Note**: If your `next.config.js` file contains a `basePath`, it is
+	 * automatically included.
 	 */
 	exitPreviewURL?: string;
 
+	/**
+	 * Children to render adjacent to the Prismic Toolbar. The Prismic Toolbar
+	 * will be rendered last.
+	 */
 	children?: React.ReactNode;
 };
 
-/**
- * Determines if an Event object came from the Prismic Toolbar.
- *
- * @param event - Event to check.
- *
- * @returns `true` if `event` came from the Prismic Toolbar, `false` otherwise.
- */
-const isPrismicUpdateToolbarEvent = (
-	event: Event,
-): event is CustomEvent<{ ref: string }> => {
-	return (
-		"detail" in event && typeof (event as CustomEvent).detail.ref === "string"
-	);
-};
-
 /**
  * React component that sets up Prismic Previews using the Prismic Toolbar. When
  * the Prismic Toolbar send events to the browser, such as on preview updates
@@ -62,31 +58,31 @@ export function PrismicPreview({
 }: PrismicPreviewProps): JSX.Element {
 	const router = useRouter();
 
-	useEffect(() => {
-		const previewRefRepositoryName = extractPreviewRefRepositoryName(
-			getCookie("io.prismic.preview", globalThis.document.cookie) as string,
-		);
-
-		const startPreviewIfLoadedFromSharedLink = async () => {
-			if (previewRefRepositoryName === repositoryName && !router.isPreview) {
-				await fetch(updatePreviewURL);
-				window.location.reload();
+	const resolvedUpdatePreviewURL = router.basePath + updatePreviewURL;
+	const resolvedExitPreviewURL = router.basePath + exitPreviewURL;
+
+	React.useEffect(() => {
+		/**
+		 * Starts Preview Mode and refreshes the page's props.
+		 */
+		const startPreviewMode = async () => {
+			// Start Next.js Preview Mode via the given preview API endpoint.
+			const res = await globalThis.fetch(resolvedUpdatePreviewURL);
+
+			if (res.ok) {
+				globalThis.location.reload();
+			} else {
+				console.error(
+					`[<PrismicPreview>] Failed to start or update Preview Mode using the "${resolvedUpdatePreviewURL}" API endpoint. Does it exist?`,
+				);
 			}
 		};
 
-		startPreviewIfLoadedFromSharedLink();
-
 		const handlePrismicPreviewUpdate = async (event: Event) => {
-			if (isPrismicUpdateToolbarEvent(event)) {
-				// Prevent the toolbar from reloading the page.
-				event.preventDefault();
-
-				// Start Next.js Preview Mode via the given preview API endpoint.
-				await fetch(updatePreviewURL);
+			// Prevent the toolbar from reloading the page.
+			event.preventDefault();
 
-				// Reload the page with an active Preview Mode.
-				window.location.reload();
-			}
+			await startPreviewMode();
 		};
 
 		const handlePrismicPreviewEnd = async (event: Event) => {
@@ -94,40 +90,81 @@ export function PrismicPreview({
 			event.preventDefault();
 
 			// Exit Next.js Preview Mode via the given preview API endpoint.
-			await fetch(exitPreviewURL);
+			const res = await globalThis.fetch(resolvedExitPreviewURL);
 
-			// Reload the page with an active Preview Mode.
-			window.location.reload();
+			if (res.ok) {
+				globalThis.location.reload();
+			} else {
+				console.error(
+					`[<PrismicPreview>] Failed to exit Preview Mode using the "${resolvedExitPreviewURL}" API endpoint. Does it exist?`,
+				);
+			}
 		};
 
-		// Register Prismic Toolbar event handlers.
-		if (window) {
+		if (router.isPreview) {
+			// Register Prismic Toolbar event handlers.
 			window.addEventListener(
 				"prismicPreviewUpdate",
 				handlePrismicPreviewUpdate,
 			);
 			window.addEventListener("prismicPreviewEnd", handlePrismicPreviewEnd);
+		} else {
+			const prismicPreviewCookie = getCookie(
+				prismic.cookie.preview,
+				globalThis.document.cookie,
+			);
+
+			if (prismicPreviewCookie) {
+				// If a Prismic preview cookie is present, but Next.js Preview
+				// Mode is not active, we must activate Preview Mode manually.
+				//
+				// This will happen when a visitor accesses the page using a
+				// Prismic preview share link.
+
+				/**
+				 * Determines if the current location is a descendant of the app's base path.
+				 *
+				 * This is used to prevent infinite refrehes; when
+				 * `isDescendantOfBasePath` is `false`, `router.isPreview` is also `false`.
+				 *
+				 * If the app does not have a base path, this should always be `true`.
+				 */
+				const locationIsDescendantOfBasePath = window.location.href.startsWith(
+					window.location.origin + router.basePath,
+				);
+
+				const prismicPreviewCookieRepositoryName =
+					getPreviewCookieRepositoryName(prismicPreviewCookie);
+
+				if (
+					locationIsDescendantOfBasePath &&
+					prismicPreviewCookieRepositoryName === repositoryName
+				) {
+					startPreviewMode();
+				}
+			}
 		}
 
 		// On cleanup, unregister Prismic Toolbar event handlers.
 		return () => {
-			if (window) {
-				window.removeEventListener(
-					"prismicPreviewUpdate",
-					handlePrismicPreviewUpdate,
-				);
-				window.removeEventListener(
-					"prismicPreviewEnd",
-					handlePrismicPreviewEnd,
-				);
-			}
+			window.removeEventListener(
+				"prismicPreviewUpdate",
+				handlePrismicPreviewUpdate,
+			);
+			window.removeEventListener("prismicPreviewEnd", handlePrismicPreviewEnd);
 		};
-	}, []);
+	}, [
+		repositoryName,
+		resolvedExitPreviewURL,
+		resolvedUpdatePreviewURL,
+		router.isPreview,
+		router.basePath,
+	]);
 
 	return (
 		<>
-			<PrismicToolbar repositoryName={repositoryName} />
 			{children}
+			<PrismicToolbar repositoryName={repositoryName} />
 		</>
 	);
 }

package/src/enableAutoPreviews.ts

@@ -60,19 +60,17 @@ export type EnableAutoPreviewsConfig<
 export const enableAutoPreviews = <TPreviewData extends PreviewData>(
 	config: EnableAutoPreviewsConfig<TPreviewData>,
 ): void => {
-	/**
-	 * If preview data is being passed from Next Context then use queryContentFromRef
-	 */
 	if ("previewData" in config && config.previewData) {
+		// If preview data is being passed from Next Context then use queryContentFromRef
+
 		const { previewData } = config;
 
 		if (isPrismicNextPreviewData(previewData) && previewData.ref) {
 			config.client.queryContentFromRef(previewData.ref);
 		}
-		/**
-		 * If the req object is passed then use enableAutoPreviewsFromReq
-		 */
 	} else if ("req" in config && config.req) {
+		// If the req object is passed then use enableAutoPreviewsFromReq
+
 		config.client.enableAutoPreviewsFromReq(config.req);
 	}
 };

package/src/exitPreview.ts

@@ -1,4 +1,4 @@
-import { NextApiResponse, NextApiRequest } from "next";
+import type { NextApiResponse, NextApiRequest } from "next";
 
 /**
  * Configuration for `exitPreview`.
@@ -10,10 +10,18 @@ export type ExitPreviewConfig = {
 	 *
 	 * @see Next.js API route docs: {@link https://nextjs.org/docs/api-routes/introduction}
 	 */
+	// `req` is no longer used in `exitPreview()`. It previously would
+	// redirect the user to the referring URL, but it no longer has that
+	// behavior.
+	//
+	// `req` is retained as a parameter to make setting up an exit preview
+	// API route easier (this eliminates the awkward need to handle an
+	// unused `req` param).
+	//
+	// It is also retained in case it is needed in the future, such as
+	// reading headers or metadata about the request.
 	req: {
-		headers: {
-			referer?: NextApiRequest["headers"]["referer"];
-		};
+		headers: NextApiRequest["headers"];
 	};
 
 	/**
@@ -24,31 +32,21 @@ export type ExitPreviewConfig = {
 	 */
 	res: {
 		clearPreviewData: NextApiResponse["clearPreviewData"];
-		redirect: NextApiResponse["redirect"];
+		json: NextApiResponse["json"];
 	};
+
+	/**
+	 * @deprecated - This property is no longer used. It can be deleted safely.
+	 */
+	exitPreviewURL?: string;
 };
 
 /**
  * Exits Next.js's Preview Mode from within a Next.js API route.
- *
- * If the user was sent to the endpoint from a page, the user will be redirected
- * back to that page after exiting Preview Mode.
  */
 export function exitPreview(config: ExitPreviewConfig): void {
-	const { req } = config;
-	// Exit the current user from "Preview Mode". This function accepts no args.
+	// Exit the current user from Preview Mode.
 	config.res.clearPreviewData();
 
-	if (req.headers.referer) {
-		const url = new URL(req.headers.referer);
-
-		if (url.pathname !== "/api/exit-preview") {
-			// Redirect the user to the referrer page.
-			config.res.redirect(req.headers.referer);
-
-			return;
-		}
-	}
-
-	config.res.redirect("/");
+	config.res.json({ success: true });
 }

package/src/index.ts

@@ -1,10 +1,19 @@
-export type { SetPreviewDataConfig } from "./setPreviewData";
-export type { EnableAutoPreviewsConfig } from "./enableAutoPreviews";
-export type { ExitPreviewConfig as ExitPreviewParams } from "./exitPreview";
-export type { PrismicPreviewProps } from "./PrismicPreview";
 export { setPreviewData } from "./setPreviewData";
+export type { SetPreviewDataConfig } from "./setPreviewData";
+
 export { exitPreview } from "./exitPreview";
+export type { ExitPreviewConfig } from "./exitPreview";
+
 export { PrismicPreview } from "./PrismicPreview";
+export type { PrismicPreviewProps } from "./PrismicPreview";
+
 export { enableAutoPreviews } from "./enableAutoPreviews";
+export type { EnableAutoPreviewsConfig } from "./enableAutoPreviews";
+
 export { redirectToPreviewURL } from "./redirectToPreviewURL";
-export type { CreateClientConfig, PreviewConfig } from "./types";
+export type { RedirectToPreviewURLConfig } from "./redirectToPreviewURL";
+
+export { PrismicNextImage } from "./PrismicNextImage";
+export type { PrismicNextImageProps } from "./PrismicNextImage";
+
+export type { CreateClientConfig } from "./types";

package/src/lib/__PRODUCTION__.ts

@@ -0,0 +1,7 @@
+/**
+ * `true` if in the production environment, `false` otherwise.
+ *
+ * This boolean can be used to perform actions only in development environments,
+ * such as logging.
+ */
+export const __PRODUCTION__ = process.env.NODE_ENV === "production";

package/src/lib/devMsg.ts

@@ -0,0 +1,20 @@
+import { version } from "../../package.json";
+
+/**
+ * Returns a `prismic.dev/msg` URL for a given message slug.
+ *
+ * @example
+ *
+ * ```ts
+ * devMsg("missing-param");
+ * // => "https://prismic.dev/msg/next/v1.2.3/missing-param.md"
+ * ```
+ *
+ * @param slug - Slug for the message. This corresponds to a Markdown file in
+ *   the Git repository's `/messages` directory.
+ *
+ * @returns The `prismic.dev/msg` URL for the given slug.
+ */
+export const devMsg = (slug: string) => {
+	return `https://prismic.dev/msg/next/v${version}/${slug}`;
+};

package/src/lib/getCookie.ts

@@ -1,58 +1,29 @@
-/**
- * The following code is a modifed version of `es-cookie` taken from
- * https://github.com/theodorejb/es-cookie
- *
- * Copyright 2017 Theodore Brown
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.*
- */
-
 const readValue = (value: string): string => {
 	return value.replace(/%3B/g, ";");
 };
 
-export const parse = (cookieString: string): { [name: string]: string } => {
-	const result: { [name: string]: string } = {};
-	const cookies = cookieString.split("; ");
-
-	for (const cookie of cookies) {
-		const parts = cookie.split("=");
-		const value = parts.slice(1).join("=");
-		const name = readValue(parts[0]).replace(/%3D/g, "=");
-		result[name] = readValue(value);
-	}
-
-	return result;
-};
-
-const getAll = (cookieStore: string): { [name: string]: string } =>
-	parse(cookieStore);
-
 /**
  * Returns the value of a cookie from a given cookie store.
  *
- * @param name - Of the cookie.
- * @param cookieStore - The stringified cookie store from which to read the cookie.
+ * @param name - Name of the cookie.
+ * @param cookieJar - The stringified cookie store from which to read the cookie.
  *
  * @returns The value of the cookie, if it exists.
  */
 export const getCookie = (
 	name: string,
-	cookieStore: string,
-): string | undefined => getAll(cookieStore)[name];
+	cookieJar: string,
+): string | undefined => {
+	const cookies = cookieJar.split("; ");
+
+	for (const cookie of cookies) {
+		const parts = cookie.split("=");
+		const thisName = readValue(parts[0]).replace(/%3D/g, "=");
+
+		if (thisName === name) {
+			const value = parts.slice(1).join("=");
+
+			return readValue(value);
+		}
+	}
+};

package/src/lib/getPreviewCookieRepositoryName.ts

@@ -0,0 +1,14 @@
+/**
+ * Extracts preview reference repo name from stringified Prismic preview cookie
+ *
+ * @param previewCookie - The Prismic preview cookie.
+ *
+ * @returns The repository name for the Prismic preview cookie. If the cookie
+ *   represents an inactive preview session, `undefined` will be returned.
+ */
+export const getPreviewCookieRepositoryName = (
+	previewCookie: string,
+): string | undefined => {
+	return (decodeURIComponent(previewCookie).match(/"(.+).prismic.io"/) ||
+		[])[1];
+};

package/src/redirectToPreviewURL.ts

@@ -1,7 +1,6 @@
-import { NextApiRequest } from "next";
-import { LinkResolverFunction } from "@prismicio/helpers";
-
-import { PreviewConfig } from "./";
+import type { Client } from "@prismicio/client";
+import type { NextApiRequest, NextApiResponse } from "next";
+import type { LinkResolverFunction } from "@prismicio/helpers";
 
 type PrismicNextQuery = {
 	documentId: string;
@@ -18,8 +17,70 @@ type PrismicNextQuery = {
  */
 const isPrismicNextQuery = (
 	query: NextApiRequest["query"],
-): query is PrismicNextQuery =>
-	typeof query.documentId === "string" && typeof query.token === "string";
+): query is PrismicNextQuery => {
+	return (
+		typeof query.documentId === "string" && typeof query.token === "string"
+	);
+};
+
+/**
+ * Preview config for enabling previews with redirectToPreviewURL
+ */
+export type RedirectToPreviewURLConfig<
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	TLinkResolverFunction extends LinkResolverFunction<any> = LinkResolverFunction,
+> = {
+	/**
+	 * The `req` object from a Next.js API route. This is given as a parameter to
+	 * the API route.
+	 *
+	 * @see Next.js API route docs: {@link https://nextjs.org/docs/api-routes/introduction}
+	 */
+	req: {
+		query: NextApiRequest["query"];
+	};
+
+	/**
+	 * The `res` object from a Next.js API route. This is given as a parameter to
+	 * the API route.
+	 *
+	 * @see Next.js API route docs: {@link https://nextjs.org/docs/api-routes/introduction}
+	 */
+	res: {
+		redirect: NextApiResponse["redirect"];
+	};
+
+	/**
+	 * The Prismic client configured for the preview session's repository.
+	 */
+	client: Client;
+
+	/**
+	 * A Link Resolver used to resolve the previewed document's URL.
+	 *
+	 * @see To learn more about Link Resolver: {@link https://prismic.io/docs/core-concepts/link-resolver-route-resolver}
+	 */
+	linkResolver?: TLinkResolverFunction;
+
+	/**
+	 * The default redirect URL if a URL cannot be determined for the previewed document.
+	 *
+	 * **Note**: If you `next.config.js` file contains a `basePath`, the
+	 * `defaultURL` option must _not_ include it. Instead, provide the `basePath`
+	 * property using the `basePath` option.
+	 */
+	defaultURL?: string;
+
+	/**
+	 * The `basePath` for the Next.js app as it is defined in `next.config.js`.
+	 * This option can be omitted if the app does not have a `basePath`.
+	 *
+	 * @remarks
+	 * The API route is unable to detect the app's `basePath` automatically. It
+	 * must be provided to `redirectToPreviewURL()` manually.
+	 */
+	basePath?: string;
+};
 
 /**
  * Redirects a user to the URL of a previewed Prismic document from within a
@@ -28,26 +89,22 @@ const isPrismicNextQuery = (
 export async function redirectToPreviewURL<
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	TLinkResolverFunction extends LinkResolverFunction<any>,
->({
-	req,
-	res,
-	client,
-	linkResolver,
-	defaultURL = "/",
-}: PreviewConfig<TLinkResolverFunction>): Promise<void> {
-	if (isPrismicNextQuery(req.query)) {
-		const { documentId, token } = req.query;
-		const previewUrl = await client.resolvePreviewURL({
-			linkResolver,
+>(config: RedirectToPreviewURLConfig<TLinkResolverFunction>): Promise<void> {
+	const defaultURL = config.defaultURL || "/";
+	const basePath = config.basePath || "";
+
+	if (isPrismicNextQuery(config.req.query)) {
+		const previewUrl = await config.client.resolvePreviewURL({
+			linkResolver: config.linkResolver,
 			defaultURL,
-			documentID: documentId,
-			previewToken: token,
+			documentID: config.req.query.documentId,
+			previewToken: config.req.query.token,
 		});
 
-		res.redirect(previewUrl);
+		config.res.redirect(basePath + previewUrl);
 
 		return;
 	}
 
-	res.redirect(defaultURL);
+	config.res.redirect(basePath + defaultURL);
 }

package/src/types.ts

@@ -1,6 +1,4 @@
-import { PreviewData, NextApiRequest, NextApiResponse } from "next";
-import { LinkResolverFunction } from "@prismicio/helpers";
-import { Client } from "@prismicio/client";
+import { PreviewData, NextApiRequest } from "next";
 
 /**
  * Configuration for creating a Prismic client with automatic preview support in
@@ -22,48 +20,3 @@ export type CreateClientConfig = {
 	 */
 	req?: NextApiRequest;
 };
-
-/**
- * Preview config for enabling previews with redirectToPreviewURL
- */
-export type PreviewConfig<
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	TLinkResolverFunction extends LinkResolverFunction<any> = LinkResolverFunction,
-> = {
-	/**
-	 * The `req` object from a Next.js API route. This is given as a parameter to
-	 * the API route.
-	 *
-	 * @see Next.js API route docs: {@link https://nextjs.org/docs/api-routes/introduction}
-	 */
-	req: {
-		query: NextApiRequest["query"];
-	};
-
-	/**
-	 * The `res` object from a Next.js API route. This is given as a parameter to
-	 * the API route.
-	 *
-	 * @see Next.js API route docs: {@link https://nextjs.org/docs/api-routes/introduction}
-	 */
-	res: {
-		redirect: NextApiResponse["redirect"];
-	};
-
-	/**
-	 * The Prismic client configured for the preview session's repository.
-	 */
-	client: Client;
-
-	/**
-	 * A Link Resolver used to resolve the previewed document's URL.
-	 *
-	 * @see To learn more about Link Resolver: {@link https://prismic.io/docs/core-concepts/link-resolver-route-resolver}
-	 */
-	linkResolver?: TLinkResolverFunction;
-
-	/**
-	 * The default redirect URL if a URL cannot be determined for the previewed document.
-	 */
-	defaultURL?: string;
-};

package/src/lib/extractPreviewRefRepositoryName.ts

@@ -1,60 +0,0 @@
-/**
- * Returns the repository name from an object-style Prismic ref.
- *
- * @param host - Host string
- */
-const extractFirstSubdomain = (host: string): string => host.split(".")[0];
-
-/**
- * Parses ref object from cookie and returns proper preview link
- *
- * @param previewRef - Prismic Preview reference
- */
-const extractRepositoryNameFromObjectRef = (
-	previewRef: string,
-): string | undefined => {
-	try {
-		const parsed = JSON.parse(decodeURIComponent(previewRef));
-		const keys = Object.keys(parsed);
-		const domainKey = keys.find((key) => /\.prismic\.io$/.test(key));
-
-		if (domainKey) {
-			return extractFirstSubdomain(domainKey);
-		} else {
-			return undefined;
-		}
-	} catch {
-		return undefined;
-	}
-};
-
-/**
- * Returns the repository name from a URL-style Prismic ref.
- *
- * @param previewRef - Preview ref from getCookie()
- */
-const extractRepositoryNameFromURLRef = (
-	previewRef: string,
-): string | undefined => {
-	try {
-		const url = new URL(previewRef);
-
-		return extractFirstSubdomain(url.host);
-	} catch {
-		return undefined;
-	}
-};
-
-/**
- * Extracts preview reference repo name from stringified Prismic preview cookie
- *
- * @param previewRef - Preview Reference
- */
-export const extractPreviewRefRepositoryName = (
-	previewRef: string,
-): string | undefined => {
-	return (
-		extractRepositoryNameFromObjectRef(previewRef) ||
-		extractRepositoryNameFromURLRef(previewRef)
-	);
-};