@prismicio/next 0.2.0-alpha.0 → 0.2.0

package/src/PrismicNextImage.tsx

@@ -0,0 +1,141 @@
+import Image, { ImageProps } from "next/image";
+import { buildURL, ImgixURLParams } from "imgix-url-builder";
+import * as prismicH from "@prismicio/helpers";
+import * as prismicT from "@prismicio/types";
+
+import { __PRODUCTION__ } from "./lib/__PRODUCTION__";
+import { devMsg } from "./lib/devMsg";
+
+import { imgixLoader } from "./imgixLoader";
+
+const castInt = (input: string | number | undefined): number | undefined => {
+	if (typeof input === "number" || typeof input === "undefined") {
+		return input;
+	} else {
+		const parsed = Number.parseInt(input);
+
+		if (Number.isNaN(parsed)) {
+			return undefined;
+		} else {
+			return parsed;
+		}
+	}
+};
+
+export type PrismicNextImageProps = Omit<ImageProps, "src" | "alt"> & {
+	/**
+	 * The Prismic Image field or thumbnail to render.
+	 */
+	field: prismicT.ImageFieldImage | null | undefined;
+
+	/**
+	 * An object of Imgix URL API parameters to transform the image.
+	 *
+	 * @see https://docs.imgix.com/apis/rendering
+	 */
+	imgixParams?: ImgixURLParams;
+
+	/**
+	 * Declare an image as decorative by providing `alt=""`.
+	 *
+	 * See:
+	 * https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/alt#decorative_images
+	 */
+	alt?: "";
+
+	/**
+	 * Declare an image as decorative only if the Image field does not have
+	 * alternative text by providing `fallbackAlt=""`.
+	 *
+	 * See:
+	 * https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/alt#decorative_images
+	 */
+	fallbackAlt?: "";
+
+	/**
+	 * Rendered when the field is empty. If a fallback is not given, `null` will
+	 * be rendered.
+	 */
+	fallback?: React.ReactNode;
+};
+
+/**
+ * React component that renders an image from a Prismic Image field or one of
+ * its thumbnails using `next/image`. It will automatically set the `alt`
+ * attribute using the Image field's `alt` property.
+ *
+ * It uses an Imgix URL-based loader by default. A custom loader can be provided
+ * with the `loader` prop. If you would like to use the Next.js Image
+ * Optimization API instead, set `loader={undefined}`.
+ *
+ * @param props - Props for the component.
+ *
+ * @returns A responsive image component using `next/image` for the given Image
+ *   field.
+ * @see To learn more about `next/image`, see: https://nextjs.org/docs/api-reference/next/image
+ */
+export const PrismicNextImage = ({
+	field,
+	imgixParams = {},
+	alt,
+	fallbackAlt,
+	fill,
+	width,
+	height,
+	fallback = null,
+	...restProps
+}: PrismicNextImageProps): JSX.Element => {
+	if (!__PRODUCTION__) {
+		if (typeof alt === "string" && alt !== "") {
+			console.warn(
+				`[PrismicNextImage] The "alt" prop can only be used to declare an image as decorative by passing an empty string (alt="") but was provided a non-empty string. You can resolve this warning by removing the "alt" prop or changing it to alt="". For more details, see ${devMsg(
+					"alt-must-be-an-empty-string",
+				)}`,
+			);
+		}
+
+		if (typeof fallbackAlt === "string" && fallbackAlt !== "") {
+			console.warn(
+				`[PrismicNextImage] The "fallbackAlt" prop can only be used to declare an image as decorative by passing an empty string (fallbackAlt="") but was provided a non-empty string. You can resolve this warning by removing the "fallbackAlt" prop or changing it to fallbackAlt="". For more details, see ${devMsg(
+					"alt-must-be-an-empty-string",
+				)}`,
+			);
+		}
+	}
+
+	if (prismicH.isFilled.imageThumbnail(field)) {
+		const src = buildURL(field.url, imgixParams);
+
+		const ar = field.dimensions.width / field.dimensions.height;
+
+		const castedWidth = castInt(width);
+		const castedHeight = castInt(height);
+
+		let resolvedWidth = castedWidth ?? field.dimensions.width;
+		let resolvedHeight = castedHeight ?? field.dimensions.width;
+
+		if (castedWidth != null && castedHeight == null) {
+			resolvedHeight = castedWidth / ar;
+		} else if (castedWidth == null && castedHeight != null) {
+			resolvedWidth = castedHeight * ar;
+		}
+
+		return (
+			<Image
+				src={src}
+				width={fill ? undefined : resolvedWidth}
+				height={fill ? undefined : resolvedHeight}
+				// A non-null assertion is required since we
+				// can't statically know if an alt attribute is
+				// available.
+				// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+				alt={(alt ?? (field.alt || fallbackAlt))!}
+				fill={fill}
+				loader={imgixLoader}
+				{...restProps}
+			/>
+		);
+	} else {
+		return <>{fallback}</>;
+	}
+};

package/src/PrismicPreview.tsx

@@ -1,10 +1,9 @@
 import * as React from "react";
-import * as prismic from "@prismicio/client";
-import { PrismicToolbar } from "@prismicio/react";
 import { useRouter } from "next/router";
+import Script from "next/script";
 
-import { getCookie } from "./lib/getCookie";
-import { extractPreviewRefRepositoryName } from "./lib/extractPreviewRefRepositoryName";
+import { getPrismicPreviewCookie } from "./lib/getPrismicPreviewCookie";
+import { getPreviewCookieRepositoryName } from "./lib/getPreviewCookieRepositoryName";
 
 /**
  * Props for `<PrismicPreview>`.
@@ -41,45 +40,6 @@ export type PrismicPreviewProps = {
 	children?: React.ReactNode;
 };
 
-/**
- * Updates (or starts) Next.js Preview Mode using a given API endpoint and
- * reloads the page.
- *
- * @param updatePreviewURL - The API endpoint that sets Preview Mode data.
- */
-const updatePreviewMode = async (updatePreviewURL: string): Promise<void> => {
-	// Start Next.js Preview Mode via the given preview API endpoint.
-	const res = await globalThis.fetch(updatePreviewURL);
-
-	if (res.ok) {
-		// Reload the page with an active Preview Mode.
-		window.location.reload();
-	} else {
-		console.error(
-			`[<PrismicPreview>] Failed to start or update Preview Mode using the "${updatePreviewURL}" API endpoint. Does it exist?`,
-		);
-	}
-};
-
-/**
- * Exits Next.js Preview Mode using a given API endpoint and reloads the page.
- *
- * @param exitPreviewURL - The API endpoint that exits Preview Mode.
- */
-const exitPreviewMode = async (exitPreviewURL: string): Promise<void> => {
-	// Exit Next.js Preview Mode via the given exit preview API endpoint.
-	const res = await globalThis.fetch(exitPreviewURL);
-
-	if (res.ok) {
-		// Reload the page with an inactive Preview Mode.
-		window.location.reload();
-	} else {
-		console.error(
-			`[<PrismicPreview>] Failed to exit Preview Mode using the "${exitPreviewURL}" API endpoint. Does it exist?`,
-		);
-	}
-};
-
 /**
  * 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
@@ -91,10 +51,10 @@ const exitPreviewMode = async (exitPreviewURL: string): Promise<void> => {
  */
 export function PrismicPreview({
 	repositoryName,
+	children,
 	updatePreviewURL = "/api/preview",
 	exitPreviewURL = "/api/exit-preview",
-	children,
-}: PrismicPreviewProps): JSX.Element {
+}: PrismicPreviewProps): React.ReactNode {
 	const router = useRouter();
 
 	const resolvedUpdatePreviewURL = router.basePath + updatePreviewURL;
@@ -102,64 +62,88 @@ export function PrismicPreview({
 
 	React.useEffect(() => {
 		/**
-		 * The Prismic preview cookie.
-		 */
-		const previewCookie = getCookie(prismic.cookie.preview);
-
-		/**
-		 * Determines if the current Prismic preview session is for the repository
-		 * configured for this instance of `<PrismicPreview>`.
-		 */
-		const prismicPreviewSessionIsForThisRepo = Boolean(
-			previewCookie &&
-				extractPreviewRefRepositoryName(previewCookie) === repositoryName,
-		);
-
-		/**
-		 * 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`.
+		 * Starts Preview Mode and refreshes the page's props.
 		 */
-		const locationIsDescendantOfBasePath = window.location.href.startsWith(
-			window.location.origin + router.basePath,
-		);
-
-		/**
-		 * Determines if the current user loaded the page from a share link.
-		 *
-		 * Currently, we can only deduce this by checking if router.isPreview is
-		 * false (i.e. Preview Mode is inactive) and a Prismic preview cookie is present.
-		 */
-		const loadedFromShareLink = !router.isPreview && previewCookie;
-
-		if (
-			prismicPreviewSessionIsForThisRepo &&
-			locationIsDescendantOfBasePath &&
-			loadedFromShareLink
-		) {
-			updatePreviewMode(resolvedUpdatePreviewURL);
-
-			return;
-		}
+		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?`,
+				);
+			}
+		};
 
 		const handlePrismicPreviewUpdate = async (event: Event) => {
 			// Prevent the toolbar from reloading the page.
 			event.preventDefault();
-			await updatePreviewMode(resolvedUpdatePreviewURL);
+
+			await startPreviewMode();
 		};
 
 		const handlePrismicPreviewEnd = async (event: Event) => {
 			// Prevent the toolbar from reloading the page.
 			event.preventDefault();
-			await exitPreviewMode(resolvedExitPreviewURL);
+
+			// Exit Next.js Preview Mode via the given preview API endpoint.
+			const res = await globalThis.fetch(resolvedExitPreviewURL);
+
+			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.
-		window.addEventListener("prismicPreviewUpdate", handlePrismicPreviewUpdate);
-		window.addEventListener("prismicPreviewEnd", handlePrismicPreviewEnd);
+		if (router.isPreview) {
+			// Register Prismic Toolbar event handlers.
+			window.addEventListener(
+				"prismicPreviewUpdate",
+				handlePrismicPreviewUpdate,
+			);
+			window.addEventListener("prismicPreviewEnd", handlePrismicPreviewEnd);
+		} else {
+			const prismicPreviewCookie = getPrismicPreviewCookie(
+				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 () => {
@@ -171,8 +155,8 @@ export function PrismicPreview({
 		};
 	}, [
 		repositoryName,
-		resolvedUpdatePreviewURL,
 		resolvedExitPreviewURL,
+		resolvedUpdatePreviewURL,
 		router.isPreview,
 		router.basePath,
 	]);
@@ -180,7 +164,10 @@ export function PrismicPreview({
 	return (
 		<>
 			{children}
-			<PrismicToolbar repositoryName={repositoryName} />
+			<Script
+				src={`https://static.cdn.prismic.io/prismic.js?repo=${repositoryName}&new=true`}
+				strategy="lazyOnload"
+			/>
 		</>
 	);
 }

package/src/enableAutoPreviews.ts

@@ -10,7 +10,8 @@ interface PrismicNextPreviewData {
  *
  * @param previewData - The Next.js preview data object to check.
  *
- * @returns `true` if `previewData` contains Prismic preview data, `false` otherwise.
+ * @returns `true` if `previewData` contains Prismic preview data, `false`
+ *   otherwise.
  */
 const isPrismicNextPreviewData = (
 	previewData: PreviewData,
@@ -45,7 +46,8 @@ export type EnableAutoPreviewsConfig<
 			/**
 			 * A Next.js API endpoint request object.
 			 *
-			 * Pass a `req` object when using `enableAutoPreviews` in a Next.js API endpoint.
+			 * Pass a `req` object when using `enableAutoPreviews` in a Next.js API
+			 * endpoint.
 			 */
 			req?: HttpRequestLike;
 	  }

package/src/exitPreview.ts

@@ -1,4 +1,4 @@
-import type { NextApiRequest, NextApiResponse } from "next";
+import type { NextApiResponse, NextApiRequest } from "next";
 
 /**
  * Configuration for `exitPreview`.
@@ -14,13 +14,15 @@ export type ExitPreviewConfig = {
 	// 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).
+	// `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: Pick<NextApiRequest, "headers">;
+	req: {
+		headers: NextApiRequest["headers"];
+	};
 
 	/**
 	 * The `res` object from a Next.js API route. This is given as a parameter to
@@ -28,7 +30,11 @@ export type ExitPreviewConfig = {
 	 *
 	 * @see Next.js API route docs: {@link https://nextjs.org/docs/api-routes/introduction}
 	 */
-	res: Pick<NextApiResponse, "clearPreviewData" | "json">;
+	res: {
+		clearPreviewData: NextApiResponse["clearPreviewData"];
+		status: NextApiResponse["status"];
+		json: NextApiResponse["json"];
+	};
 };
 
 /**
@@ -38,5 +44,7 @@ export function exitPreview(config: ExitPreviewConfig): void {
 	// Exit the current user from Preview Mode.
 	config.res.clearPreviewData();
 
-	config.res.json({ success: true });
+	// 205 status is used to prevent CDN-level caching. The default 200
+	// status code is typically treated as non-changing and cacheable.
+	config.res.status(205).json({ success: true });
 }

package/src/imgixLoader.ts

@@ -0,0 +1,25 @@
+import { ImageLoaderProps } from "next/image";
+import { buildURL, ImgixURLParams } from "imgix-url-builder";
+
+/**
+ * A `next/image` loader for Imgix, which Prismic uses, with an optional
+ * collection of default Imgix parameters.
+ *
+ * @see To learn about `next/image` loaders: https://nextjs.org/docs/api-reference/next/image#loader
+ * @see To learn about Imgix's URL API: https://docs.imgix.com/apis/rendering
+ */
+export const imgixLoader = (args: ImageLoaderProps): string => {
+	const url = new URL(args.src);
+
+	const params: ImgixURLParams = {
+		fit: (url.searchParams.get("fit") as ImgixURLParams["fit"]) || "max",
+		w: args.width,
+		h: undefined,
+	};
+
+	if (args.quality) {
+		params.q = args.quality;
+	}
+
+	return buildURL(args.src, params);
+};

package/src/index.ts

@@ -1,16 +1,21 @@
-export { setPreviewData } from "./setPreviewData";
-export type { SetPreviewDataConfig } from "./setPreviewData";
+export { setPreviewData, SetPreviewDataConfig } from "./setPreviewData";
 
-export { exitPreview } from "./exitPreview";
-export type { ExitPreviewConfig } from "./exitPreview";
+export { exitPreview, ExitPreviewConfig } from "./exitPreview";
 
-export { PrismicPreview } from "./PrismicPreview";
-export type { PrismicPreviewProps } from "./PrismicPreview";
+export { PrismicPreview, PrismicPreviewProps } from "./PrismicPreview";
 
-export { enableAutoPreviews } from "./enableAutoPreviews";
-export type { EnableAutoPreviewsConfig } from "./enableAutoPreviews";
+export {
+	EnableAutoPreviewsConfig,
+	enableAutoPreviews,
+} from "./enableAutoPreviews";
 
-export { redirectToPreviewURL } from "./redirectToPreviewURL";
-export type { RedirectToPreviewURLConfig } from "./redirectToPreviewURL";
+export {
+	RedirectToPreviewURLConfig,
+	redirectToPreviewURL,
+} from "./redirectToPreviewURL";
 
-export type { CreateClientConfig } from "./types";
+export { PrismicNextImage, PrismicNextImageProps } from "./PrismicNextImage";
+
+export { imgixLoader } from "./imgixLoader";
+
+export { 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/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/lib/getPrismicPreviewCookie.ts

@@ -0,0 +1,33 @@
+import * as prismic from "@prismicio/client";
+
+const readValue = (value: string): string => {
+	return value.replace(/%3B/g, ";");
+};
+
+/**
+ * Returns the value of a cookie from a given cookie store.
+ *
+ * @param cookieJar - The stringified cookie store from which to read the
+ *   cookie.
+ *
+ * @returns The value of the cookie, if it exists.
+ */
+export const getPrismicPreviewCookie = (
+	cookieJar: string,
+): string | undefined => {
+	const cookies = cookieJar.split("; ");
+
+	let value: string | undefined;
+
+	for (const cookie of cookies) {
+		const parts = cookie.split("=");
+		const name = readValue(parts[0]).replace(/%3D/g, "=");
+
+		if (name === prismic.cookie.preview) {
+			value = readValue(parts.slice(1).join("="));
+			continue;
+		}
+	}
+
+	return value;
+};

package/src/redirectToPreviewURL.ts

@@ -36,7 +36,9 @@ export type RedirectToPreviewURLConfig<
 	 *
 	 * @see Next.js API route docs: {@link https://nextjs.org/docs/api-routes/introduction}
 	 */
-	req: Pick<NextApiRequest, "query">;
+	req: {
+		query: NextApiRequest["query"];
+	};
 
 	/**
 	 * The `res` object from a Next.js API route. This is given as a parameter to
@@ -44,7 +46,9 @@ export type RedirectToPreviewURLConfig<
 	 *
 	 * @see Next.js API route docs: {@link https://nextjs.org/docs/api-routes/introduction}
 	 */
-	res: Pick<NextApiResponse, "redirect">;
+	res: {
+		redirect: NextApiResponse["redirect"];
+	};
 
 	/**
 	 * The Prismic client configured for the preview session's repository.
@@ -59,11 +63,12 @@ export type RedirectToPreviewURLConfig<
 	linkResolver?: TLinkResolverFunction;
 
 	/**
-	 * The default redirect URL if a URL cannot be determined for the previewed document.
+	 * The default redirect URL if a URL cannot be determined for the previewed
+	 * document.
 	 *
-	 * **Note**: If your `next.config.js` file contains a `basePath`, you must
-	 * include the `basePath` as part of this option. `redirectToPreviewURL()`
-	 * cannot read your global `basePath`.
+	 * **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;
 

package/src/setPreviewData.ts

@@ -11,7 +11,10 @@ export type SetPreviewDataConfig = {
 	 *
 	 * @see Next.js API route docs: {@link https://nextjs.org/docs/api-routes/introduction}
 	 */
-	req: Pick<NextApiRequest, "query" | "cookies">;
+	req: {
+		query: NextApiRequest["query"];
+		cookies: NextApiRequest["cookies"];
+	};
 
 	/**
 	 * The `res` object from a Next.js API route. This is given as a parameter to
@@ -19,7 +22,9 @@ export type SetPreviewDataConfig = {
 	 *
 	 * @see Next.js API route docs: {@link https://nextjs.org/docs/api-routes/introduction}
 	 */
-	res: Pick<NextApiResponse, "setPreviewData">;
+	res: {
+		setPreviewData: NextApiResponse["setPreviewData"];
+	};
 };
 
 /**

package/src/types.ts

@@ -1,4 +1,5 @@
-import { PreviewData, NextApiRequest } from "next";
+import type { PreviewData, NextApiRequest } from "next";
+import type { ClientConfig } from "@prismicio/client";
 
 /**
  * Configuration for creating a Prismic client with automatic preview support in
@@ -19,4 +20,4 @@ export type CreateClientConfig = {
 	 * Pass a `req` object when using in a Next.js API endpoint.
 	 */
 	req?: NextApiRequest;
-};
+} & ClientConfig;