fix(preview): say that previews need a preview URL and a simulator URL

evals/configure-repositories.eval.ts

@@ -5,6 +5,7 @@ import {
 	getPreviews,
 	getRepository,
 	getWebhooks,
+	setSimulatorUrl,
 } from "../test/prismic";
 import { it, trials } from "./it";
 
@@ -22,6 +23,7 @@ it.for(trials)(
 	"updates previews for production after a deploy",
 	async (_, { agent, expect, repo, token, host }) => {
 		await addPreview("http://localhost:3000/api/preview", "Development", { repo, token, host });
+		await setSimulatorUrl("http://localhost:3000/slice-simulator", { repo, token, host });
 
 		const result = await agent(
 			`We just deployed the site to https://example.com. Set up content previews for production.`,

src/commands/index.ts

@@ -34,6 +34,15 @@ export default createCommandRouter({
 			it directly. There is no route command.
 			Run \`prismic docs view routes\` for path keywords and route properties.
 		`,
+		PREVIEWS: `
+			Writers use previews to see draft content before it is published.
+			Previews need two settings. After a deploy, set both:
+			  prismic preview add https://example.com/api/preview
+			  prismic preview set-simulator https://example.com
+			A repository can hold multiple preview URLs but only one simulator URL,
+			which the Page Builder loads live slice previews from.
+			Run \`prismic docs view previews\` for details.
+		`,
 	},
 	commands: {
 		init: {
@@ -91,7 +100,7 @@ export default createCommandRouter({
 		},
 		preview: {
 			handler: preview,
-			description: "Manage preview configurations",
+			description: "Manage preview and simulator URLs",
 		},
 		token: {
 			handler: token,

src/commands/preview.ts

@@ -6,19 +6,26 @@ import previewSetSimulator from "./preview-set-simulator";
 
 export default createCommandRouter({
 	name: "prismic preview",
-	description: "Manage preview configurations in a Prismic repository.",
+	description: "Manage previews in a Prismic repository.",
+	sections: {
+		EXAMPLES: `
+			Set up previews after a deploy, using both settings:
+			  prismic preview add https://example.com/api/preview
+			  prismic preview set-simulator https://example.com
+		`,
+	},
 	commands: {
 		add: {
 			handler: previewAdd,
-			description: "Add a preview configuration",
+			description: "Add a preview URL",
 		},
 		list: {
 			handler: previewList,
-			description: "List preview configurations",
+			description: "List preview URLs and the simulator URL",
 		},
 		remove: {
 			handler: previewRemove,
-			description: "Remove a preview configuration",
+			description: "Remove a preview URL",
 		},
 		"set-simulator": {
 			handler: previewSetSimulator,

test/index.test.ts

@@ -8,6 +8,7 @@ it("supports --help", async ({ expect, prismic }) => {
 	expect(exitCode, stderr).toBe(0);
 	expect(stdout).toContain("prismic <command> [options]");
 	expect(stdout).toContain("ROUTES");
+	expect(stdout).toContain("PREVIEWS");
 	expect(stdout).not.toContain("starter");
 });
 

test/preview.test.ts

@@ -11,3 +11,10 @@ it("supports --help", async ({ expect, prismic }) => {
 	expect(exitCode, stderr).toBe(0);
 	expect(stdout).toContain("prismic preview <command> [options]");
 });
+
+it("shows how to set up both preview settings", async ({ expect, prismic }) => {
+	const { stdout, stderr, exitCode } = await prismic("preview", ["--help"]);
+	expect(exitCode, stderr).toBe(0);
+	expect(stdout).toContain("EXAMPLES");
+	expect(stdout).toContain("prismic preview set-simulator");
+});