@prismicio/next 1.7.1 → 2.0.0-alpha.0

package/src/pages/PrismicPreview.tsx

@@ -0,0 +1,145 @@
+import { type ReactNode, useEffect, JSX } from "react";
+import { useRouter } from "next/router";
+import Script from "next/script";
+import { getToolbarSrc, cookie as prismicCookie } from "@prismicio/client";
+
+/** Props for `<PrismicPreview>`. */
+export type PrismicPreviewProps = {
+	/**
+	 * The name of your Prismic repository. A Prismic Toolbar will be registered
+	 * using this repository.
+	 */
+	repositoryName: string;
+
+	/**
+	 * The URL of your app's Prismic preview endpoint (default: `/api/preview`).
+	 * This URL will be fetched on preview update events.
+	 */
+	updatePreviewURL?: string;
+
+	/**
+	 * The URL of your app's exit preview endpoint (default: `/api/exit-preview`).
+	 * This URL will be fetched on preview exit events.
+	 */
+	exitPreviewURL?: string;
+
+	/** Children to render adjacent to the Prismic Toolbar. */
+	children?: ReactNode;
+};
+
+/**
+ * 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
+ * and exiting, this component will automatically refresh the page with the
+ * changes.
+ *
+ * This component can be wrapped around your app or added anywhere in your app's
+ * tree. It must be rendered on every page.
+ */
+export function PrismicPreview(props: PrismicPreviewProps): JSX.Element {
+	const {
+		repositoryName,
+		updatePreviewURL = "/api/preview",
+		exitPreviewURL = "/api/exit-preview",
+		children,
+	} = props;
+
+	const router = useRouter();
+
+	const toolbarSrc = getToolbarSrc(repositoryName);
+
+	useEffect(() => {
+		const controller = new AbortController();
+
+		window.addEventListener("prismicPreviewUpdate", onUpdate, {
+			signal: controller.signal,
+		});
+		window.addEventListener("prismicPreviewEnd", onEnd, {
+			signal: controller.signal,
+		});
+
+		// Start the preview for preview share links. Previews from
+		// share links do not go to the `updatePreviewURL` like a normal
+		// preview.
+		//
+		// We check that the current URL is a descendant of the base
+		// path to prevent infinite refrehes.
+		if (
+			window.location.href.startsWith(
+				window.location.origin + router.basePath,
+			) &&
+			getPreviewCookieRepositoryName() === repositoryName &&
+			!router.isPreview
+		) {
+			start();
+		}
+
+		function onEnd(event: Event) {
+			event.preventDefault();
+			fetch(router.basePath + exitPreviewURL, { signal: controller.signal })
+				.then((res) => {
+					if (!res.ok) {
+						console.error(
+							`[<PrismicPreview>] Failed to exit Preview Mode using the "${exitPreviewURL}" API endpoint. Does it exist?`,
+						);
+
+						return;
+					}
+
+					refresh();
+				})
+				.catch(() => {});
+		}
+
+		function onUpdate(event: Event) {
+			event.preventDefault();
+			start();
+		}
+
+		function start() {
+			// We check `opaqueredirect` because we don't care if
+			// the redirect was successful or not. As long as it
+			// redirects, we know the endpoint exists and at least
+			// attempted to set preview data.
+			fetch(router.basePath + updatePreviewURL, {
+				redirect: "manual",
+				signal: controller.signal,
+			})
+				.then((res) => {
+					if (res.type !== "opaqueredirect") {
+						console.error(
+							`[<PrismicPreview>] Failed to start or update the preview using "${updatePreviewURL}". Does it exist?`,
+						);
+
+						return;
+					}
+
+					refresh();
+				})
+				.catch(() => {});
+		}
+
+		function refresh() {
+			router.replace(router.asPath, undefined, { scroll: false });
+		}
+
+		return () => controller.abort();
+	}, [exitPreviewURL, updatePreviewURL, repositoryName, router]);
+
+	return (
+		<>
+			{children}
+			<Script src={toolbarSrc} strategy="lazyOnload" />
+		</>
+	);
+}
+
+function getPreviewCookieRepositoryName() {
+	const cookie = window.document.cookie
+		.split("; ")
+		.find((row) => row.startsWith(`${prismicCookie.preview}=`))
+		?.split("=")[1];
+
+	return (decodeURIComponent(cookie ?? "").match(/"([^"]+)\.prismic\.io"/) ||
+		[])[1];
+}

package/src/pages/enableAutoPreviews.ts

@@ -0,0 +1,62 @@
+import type { PreviewData } from "next";
+import type { Client } from "@prismicio/client";
+
+import type { NextApiRequestLike } from "./types.js";
+
+/**
+ * Configuration for `enableAutoPreviews`.
+ *
+ * @typeParam TPreviewData - Next.js preview data object.
+ */
+export type EnableAutoPreviewsConfig = {
+	/** Prismic client with which automatic previews will be enabled. */
+	// `Pick` is used to use the smallest possible subset of
+	// `prismic.Client`. Doing this reduces the surface area for breaking
+	// type changes.
+	client: Pick<Client, "queryContentFromRef" | "enableAutoPreviewsFromReq">;
+
+	/**
+	 * The `previewData` object provided in the `getStaticProps()` or
+	 * `getServerSideProps()` context object.
+	 */
+	previewData?: PreviewData;
+
+	/**
+	 * The `req` object from a Next.js API route.
+	 *
+	 * @see Next.js API route docs: \<https://nextjs.org/docs/api-routes/introduction\>
+	 */
+	req?: NextApiRequestLike;
+};
+
+/**
+ * Configures a Prismic client to automatically query draft content during a
+ * preview session. It either takes in a Next.js `getStaticProps` context object
+ * or a Next.js API endpoint request object.
+ *
+ * @param config - Configuration for the function.
+ */
+export function enableAutoPreviews(config: EnableAutoPreviewsConfig): void {
+	if ("previewData" in config && config.previewData) {
+		// Assume we are in `getStaticProps()` or
+		// `getServerSideProps()` with active Preview Mode.
+
+		if (isPrismicPreviewData(config.previewData)) {
+			config.client.queryContentFromRef(config.previewData.ref);
+		}
+
+		return;
+	}
+
+	if ("req" in config && config.req) {
+		// Assume we are in an API Route.
+
+		config.client.enableAutoPreviewsFromReq(config.req);
+
+		return;
+	}
+}
+
+function isPrismicPreviewData(input: unknown): input is { ref: string } {
+	return typeof input === "object" && input !== null && "ref" in input;
+}

package/src/pages/exitPreview.ts

@@ -0,0 +1,45 @@
+import type { NextApiRequestLike, NextApiResponseLike } from "./types.js";
+
+/** Configuration for `exitPreview()`. */
+export type ExitPreviewAPIRouteConfig = {
+	/**
+	 * The `req` object from a Next.js API route.
+	 *
+	 * @see Next.js API route docs: \<https://nextjs.org/docs/api-routes/introduction\>
+	 */
+	req?: NextApiRequestLike;
+
+	/**
+	 * The `res` object from a Next.js API route.
+	 *
+	 * @see Next.js API route docs: \<https://nextjs.org/docs/api-routes/introduction\>
+	 */
+	res: NextApiResponseLike;
+};
+
+/**
+ * Ends a Prismic preview session within a Next.js app. This function should be
+ * used in an API route.
+ *
+ * @example
+ *
+ * ```typescript
+ * // src/pages/api/exit-preview.js
+ *
+ * import { exitPreview } from "@prismicio/next";
+ *
+ * export default function handler(_req, res) {
+ * 	return exitPreview({ res });
+ * }
+ * ```
+ */
+export function exitPreview(config: ExitPreviewAPIRouteConfig): void {
+	config.res.clearPreviewData();
+
+	// `Cache-Control` header is used to prevent CDN-level caching.
+	config.res.setHeader("Cache-Control", "no-store");
+
+	config.res.json({ success: true });
+
+	return;
+}

package/src/pages/index.ts

@@ -0,0 +1,27 @@
+export { PrismicNextLink } from "../PrismicNextLink.js";
+export { type PrismicNextLinkProps } from "../PrismicNextLink.js";
+
+export { PrismicNextImage } from "../PrismicNextImage.js";
+export { type PrismicNextImageProps } from "../PrismicNextImage.js";
+
+export { imgixLoader } from "../imgixLoader.js";
+
+export { PrismicPreview } from "./PrismicPreview.js";
+export type { PrismicPreviewProps } from "./PrismicPreview.js";
+
+export { enableAutoPreviews } from "./enableAutoPreviews.js";
+export type { EnableAutoPreviewsConfig } from "./enableAutoPreviews.js";
+
+export { redirectToPreviewURL } from "./redirectToPreviewURL.js";
+export type { RedirectToPreviewURLConfig } from "./redirectToPreviewURL.js";
+
+export { exitPreview } from "./exitPreview.js";
+export type { ExitPreviewAPIRouteConfig } from "./exitPreview.js";
+
+export { setPreviewData } from "./setPreviewData.js";
+export type { SetPreviewDataConfig } from "./setPreviewData.js";
+
+export type { CreateClientConfig } from "./types.js";
+
+export { createLocaleRedirect } from "../createLocaleRedirect.js";
+export type { CreateLocaleRedirectConfig } from "../createLocaleRedirect.js";

package/src/pages/redirectToPreviewURL.ts

@@ -0,0 +1,77 @@
+import type { LinkResolverFunction, Client } from "@prismicio/client";
+
+import type { NextApiRequestLike, NextApiResponseLike } from "./types.js";
+
+export type RedirectToPreviewURLConfig = {
+	/** The Prismic client configured for the preview session's repository. */
+	// `Pick` is used to use the smallest possible subset of
+	// `prismic.Client`. Doing this reduces the surface area for breaking
+	// type changes.
+	client: Pick<Client, "resolvePreviewURL">;
+
+	/**
+	 * The `req` object from a Next.js API route.
+	 *
+	 * @see Next.js API route docs: \<https://nextjs.org/docs/pages/building-your-application/routing/api-routes\>
+	 */
+	req: NextApiRequestLike;
+
+	/**
+	 * The `res` object from a Next.js API route.
+	 *
+	 * @see Next.js API route docs: \<https://nextjs.org/docs/pages/building-your-application/routing/api-routes\>
+	 */
+	res: NextApiResponseLike;
+
+	/**
+	 * 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?: LinkResolverFunction;
+
+	/**
+	 * 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 Router Handler or API route is unable to detect the app's `basePath`
+	 * automatically. It must be provided to `redirectToPreviewURL()` manually.
+	 */
+	basePath?: string;
+};
+
+export async function redirectToPreviewURL(
+	config: RedirectToPreviewURLConfig,
+): Promise<void> {
+	const {
+		client,
+		req,
+		res,
+		linkResolver,
+		defaultURL = "/",
+		basePath = "",
+	} = config;
+
+	const previewToken = req.query.token?.toString();
+
+	const previewURL = await client.resolvePreviewURL({
+		linkResolver,
+		defaultURL,
+		previewToken,
+	});
+
+	res.redirect(basePath + previewURL);
+
+	return;
+}

package/src/{setPreviewData.ts → pages/setPreviewData.ts}

@@ -1,10 +1,8 @@
-import * as prismic from "@prismicio/client";
+import { cookie } from "@prismicio/client";
 
-import { NextApiRequestLike, NextApiResponseLike } from "./types";
+import type { NextApiRequestLike, NextApiResponseLike } from "./types.js";
 
-/**
- * Configuration for `setPreviewData`.
- */
+/** Configuration for `setPreviewData`. */
 export type SetPreviewDataConfig = {
 	/**
 	 * The `req` object from a Next.js API route.
@@ -21,13 +19,9 @@ export type SetPreviewDataConfig = {
 	res: NextApiResponseLike;
 };
 
-/**
- * **Only use this function in the Pages Directory (/pages).**
- *
- * Set Prismic preview data for Next.js's Preview Mode.
- */
+/** Set Prismic preview data for Next.js's Preview Mode. */
 export function setPreviewData({ req, res }: SetPreviewDataConfig): void {
-	const ref = req.query.token || req.cookies[prismic.cookie.preview];
+	const ref = req.query.token || req.cookies[cookie.preview];
 
 	if (ref) {
 		res.setPreviewData({ ref });

package/src/pages/types.ts

@@ -0,0 +1,36 @@
+import type { ClientConfig } from "@prismicio/client";
+
+import { EnableAutoPreviewsConfig } from "./enableAutoPreviews.js";
+
+/**
+ * Configuration for creating a Prismic client with automatic preview support in
+ * Next.js apps.
+ */
+export type CreateClientConfig = ClientConfig &
+	Pick<EnableAutoPreviewsConfig, "previewData" | "req">;
+
+/**
+ * The minimal set of properties needed from `next`'s `NextApiRequest` type.
+ *
+ * This request type is only compatible with API routes defined in the `pages`
+ * directory.
+ */
+export type NextApiRequestLike = {
+	query: Partial<Record<string, string | string[]>>;
+	cookies: Partial<Record<string, string>>;
+};
+
+/**
+ * The minimal set of properties needed from `next`'s `NextApiResponse` type.
+ *
+ * This request type is only compatible with API routes defined in the `pages`
+ * directory.
+ */
+export type NextApiResponseLike = {
+	redirect(url: string): NextApiResponseLike;
+	clearPreviewData(): NextApiResponseLike;
+	setHeader(name: string, value: string | string[]): NextApiResponseLike;
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	json(body: any): void;
+	setPreviewData(data: object | string): NextApiResponseLike;
+};

package/src/redirectToPreviewURL.ts

@@ -1,31 +1,32 @@
 import { redirect } from "next/navigation";
-import { cookies, draftMode } from "next/headers";
-import * as prismic from "@prismicio/client";
-
 import {
-	NextApiRequestLike,
-	NextApiResponseLike,
-	NextRequestLike,
-} from "./types";
+	cookie as prismicCookie,
+	type Client,
+	type LinkResolverFunction,
+} from "@prismicio/client";
 
-type RedirectToPreviewURLConfigBase = {
-	/**
-	 * The Prismic client configured for the preview session's repository.
-	 */
+import { NextRequestLike } from "./types.js";
+
+export type RedirectToPreviewURLConfig = {
+	/** The Prismic client configured for the preview session's repository. */
 	// `Pick` is used to use the smallest possible subset of
 	// `prismic.Client`. Doing this reduces the surface area for breaking
 	// type changes.
-	client: Pick<
-		prismic.Client,
-		"enableAutoPreviewsFromReq" | "resolvePreviewURL"
-	>;
+	client: Pick<Client, "resolvePreviewURL">;
+
+	/**
+	 * The `request` object from a Next.js Route Handler.
+	 *
+	 * @see Next.js Route Handler docs: \<https://nextjs.org/docs/app/building-your-application/routing/route-handlers\>
+	 */
+	request: NextRequestLike;
 
 	/**
 	 * 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?: prismic.LinkResolverFunction;
+	linkResolver?: LinkResolverFunction;
 
 	/**
 	 * The default redirect URL if a URL cannot be determined for the previewed
@@ -36,91 +37,39 @@ type RedirectToPreviewURLConfigBase = {
 	 * 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 Router Handler or API route is unable to detect the app's `basePath`
-	 * automatically. It must be provided to `redirectToPreviewURL()` manually.
-	 */
-	basePath?: string;
 };
 
-export type RedirectToPreviewURLRouteHandlerConfig =
-	RedirectToPreviewURLConfigBase & {
-		/**
-		 * The `request` object from a Next.js Route Handler.
-		 *
-		 * @see Next.js Route Handler docs: \<https://nextjs.org/docs/app/building-your-application/routing/route-handlers\>
-		 */
-		request: NextRequestLike;
-	};
-
-export type RedirectToPreviewURLAPIEndpointConfig =
-	RedirectToPreviewURLConfigBase & {
-		/**
-		 * The `req` object from a Next.js API route.
-		 *
-		 * @see Next.js API route docs: \<https://nextjs.org/docs/pages/building-your-application/routing/api-routes\>
-		 */
-		req: NextApiRequestLike;
-
-		/**
-		 * The `res` object from a Next.js API route.
-		 *
-		 * @see Next.js API route docs: \<https://nextjs.org/docs/pages/building-your-application/routing/api-routes\>
-		 */
-		res: NextApiResponseLike;
-	};
-
-export type RedirectToPreviewURLConfig =
-	| RedirectToPreviewURLRouteHandlerConfig
-	| RedirectToPreviewURLAPIEndpointConfig;
-
-export async function redirectToPreviewURL(
-	config: RedirectToPreviewURLRouteHandlerConfig,
-): Promise<never>;
-export async function redirectToPreviewURL(
-	config: RedirectToPreviewURLAPIEndpointConfig,
-): Promise<void>;
 export async function redirectToPreviewURL(
 	config: RedirectToPreviewURLConfig,
-): Promise<never | void> {
-	const basePath = config.basePath || "";
-	const request = "request" in config ? config.request : config.req;
-
-	config.client.enableAutoPreviewsFromReq(request);
+): Promise<never> {
+	const { client, request, linkResolver, defaultURL = "/" } = config;
+
+	// Need this to avoid the following Next.js build-time error:
+	// You're importing a component that needs next/headers. That only works
+	// in a Server Component which is not supported in the pages/ directory.
+	const { cookies, draftMode } = await import("next/headers");
+
+	const documentID =
+		request.nextUrl.searchParams.get("documentId") ?? undefined;
+
+	// Set the initial preview cookie. Setting the cookie here is necessary
+	// to support unpublished previews. Without setting it here, the page
+	// will try to render without the preview cookie, leading to a
+	// PrismicNotFound error.
+	const previewToken = request.nextUrl.searchParams.get("token") ?? undefined;
+	if (previewToken) {
+		const cookieJar = await cookies();
+		cookieJar.set(prismicCookie.preview, previewToken);
+	}
 
-	const previewUrl = await config.client.resolvePreviewURL({
-		linkResolver: config.linkResolver,
-		defaultURL: config.defaultURL || "/",
+	const previewURL = await client.resolvePreviewURL({
+		documentID,
+		previewToken,
+		defaultURL,
+		linkResolver,
 	});
 
-	if ("nextUrl" in request) {
-		(await draftMode()).enable();
-
-		// Set the initial preview cookie, if available.
-		// Setting the cookie here is necessary to support unpublished
-		// previews. Without setting it here, the page will try to
-		// render without the preview cookie, leading to a
-		// PrismicNotFound error.
-		const previewCookie = request.nextUrl.searchParams.get("token");
-		if (previewCookie) {
-			(await cookies()).set(prismic.cookie.preview, previewCookie);
-		}
+	(await draftMode()).enable();
 
-		redirect(basePath + previewUrl);
-	} else {
-		if (!("res" in config)) {
-			throw new Error(
-				"[redirectToPreviewURL] The `res` object from the API route must be provided to `redirectToPreviewURL()`.",
-			);
-		}
-
-		config.res.redirect(basePath + previewUrl);
-
-		return;
-	}
+	redirect(previewURL);
 }

package/src/types.ts

@@ -1,4 +1,3 @@
-import type { PreviewData } from "next";
 import type { ClientConfig } from "@prismicio/client";
 
 // Add Next.js-specific fetchOptions to `@prismicio/client`.
@@ -8,35 +7,8 @@ declare module "@prismicio/client" {
 	}
 }
 
-/**
- * Prismic data saved in Next.js Preview Mode's object.
- */
-export type PrismicPreviewData = {
-	ref: string;
-};
-
-/**
- * Configuration for creating a Prismic client with automatic preview support in
- * Next.js apps.
- */
-export type CreateClientConfig = ClientConfig & {
-	/**
-	 * **Only used in the Pages Directory (/pages).**
-	 *
-	 * The `previewData` object provided in the `getStaticProps()` or
-	 * `getServerSideProps()` context object.
-	 */
-	previewData?: PreviewData;
-
-	/**
-	 * **Only used in the Pages Directory (/pages).**
-	 *
-	 * The `req` object from a Next.js API route.
-	 *
-	 * @see Next.js API route docs: \<https://nextjs.org/docs/api-routes/introduction\>
-	 */
-	req?: NextApiRequestLike;
-};
+/** @deprecated Use `@prismicio/client`'s `ClientConfig`. */
+export type CreateClientConfig = ClientConfig;
 
 /**
  * The minimal set of properties needed from `next`'s `NextRequest` type.
@@ -56,29 +28,3 @@ export type NextRequestLike = {
 		};
 	};
 };
-
-/**
- * The minimal set of properties needed from `next`'s `NextApiRequest` type.
- *
- * This request type is only compatible with API routes defined in the `pages`
- * directory.
- */
-export type NextApiRequestLike = {
-	query: Partial<Record<string, string | string[]>>;
-	cookies: Partial<Record<string, string>>;
-};
-
-/**
- * The minimal set of properties needed from `next`'s `NextApiResponse` type.
- *
- * This request type is only compatible with API routes defined in the `pages`
- * directory.
- */
-export type NextApiResponseLike = {
-	redirect(url: string): NextApiResponseLike;
-	clearPreviewData(): NextApiResponseLike;
-	setHeader(name: string, value: string | string[]): NextApiResponseLike;
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	json(body: any): void;
-	setPreviewData(data: object | string): NextApiResponseLike;
-};