@nuxtjs/prismic 4.0.0 → 4.1.0-canary.a1dda93

package/src/module.ts

@@ -1,115 +1,259 @@
-import { join } from 'node:path'
-import { readFile } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
+import { existsSync } from "node:fs"
+import { readFile } from "node:fs/promises"
+import { join } from "node:path"
 
-import { defu } from 'defu'
 import {
-	defineNuxtModule,
-	createResolver,
-	addTemplate,
-	addPlugin,
-	addImports,
 	addComponent,
+	addImports,
+	addPlugin,
+	addTemplate,
+	createResolver,
+	defineNuxtModule,
 	extendPages,
 	getNuxtVersion,
-} from '@nuxt/kit'
+	useLogger,
+} from "@nuxt/kit"
+import type { ClientConfig } from "@prismicio/client"
+import { defu } from "defu"
+import { addDependency } from "nypm"
+import { readPackage } from "pkg-types"
 
-import * as prismicVue from '@prismicio/vue'
-import { setupDevToolsUI } from './devtools'
+import { name, version } from "../package.json"
 
-import { logger, fileExists } from './lib'
-import type { PrismicModuleOptions } from './types'
+/**
+ * Prismic Nuxt module options.
+ *
+ * @see {@link https://prismic.io/docs/nuxt}
+ * @see {@link https://prismic.io/docs/technical-reference/nuxtjs-prismic}
+ */
+export type PrismicModuleOptions = {
+	/**
+	 * The Prismic repository name or full Content API endpoint to init the
+	 * module's client instance used to fetch content from a Prismic repository
+	 * with.
+	 *
+	 * @example
+	 *
+	 * ```typescript
+	 * // With a repository name
+	 * createClient("my-repo")
+	 *
+	 * // With a full Prismic Content API endpoint
+	 * createClient("https://my-repo.cdn.prismic.io/api/v2")
+	 * ```
+	 *
+	 * @see {@link https://prismic.io/docs/technical-reference/prismicio-client}
+	 */
+	endpoint?: string
 
-// Options export
-export type { PrismicModuleOptions, PrismicModuleOptions as ModuleOptions } from './types'
+	/**
+	 * The Prismic environment in use by Slice Machine configured through
+	 * environment variables.
+	 *
+	 * @defaultValue `endpoint` value.
+	 *
+	 * @internal
+	 */
+	environment?: string
 
-declare module '@nuxt/schema' {
-	interface PublicRuntimeConfig {
+	/**
+	 * Configuration options that determines how content will be queries from the
+	 * Prismic repository.
+	 *
+	 * @see {@link https://prismic.io/docs/technical-reference/prismicio-client}
+	 */
+	clientConfig?: ClientConfig
+
+	/**
+	 * An optional path to a file exporting a Prismic client instance used to
+	 * fetch content from a Prismic repository to configure the module with.
+	 *
+	 * @remarks
+	 * When provided, it takes precedence over the `endpoint` and `clientConfig`
+	 * options.
+	 *
+	 * @see {@link https://prismic.io/docs/technical-reference/prismicio-client}
+	 */
+	client?: string
+
+	/**
+	 * The path to a file exporting a default link resolver used to resolve links
+	 * when route resolvers cannot be used.
+	 *
+	 * @see {@link https://prismic.io/docs/routes}
+	 */
+	linkResolver?: string
+
+	/**
+	 * Desired path of the preview page used by Prismic to enter preview session.
+	 *
+	 * @remarks
+	 * `false` can be used to disable the preview page.
+	 *
+	 * @defaultValue `"/preview"`
+	 */
+	preview?: string | false
+
+	/**
+	 * Whether to inject Prismic toolbar script.
+	 *
+	 * @remarks
+	 * The toolbar script is required for previews to work.
+	 *
+	 * @defaultValue `true`
+	 */
+	toolbar?: boolean
+
+	/** Options used by Prismic Vue components. */
+	components?: {
 		/**
-		 * `@nuxtjs/prismic` module options.
+		 * The path to a file exporting default components or shorthand definitions
+		 * for rich text and table components.
 		 *
-		 * @see Module documentation: {@link https://prismic.nuxtjs.org}
-		 * @see Prismic documentation: {@link https://prismic.io/docs/nuxt-3-setup}
+		 * @see {@link https://prismic.io/docs/fields/rich-text}
+		 * @see {@link https://prismic.io/docs/fields/table}
 		 */
+		richTextComponents?: string
+	}
+}
+
+/**
+ * Prismic Nuxt module options.
+ *
+ * @see {@link https://prismic.io/docs/nuxt}
+ * @see {@link https://prismic.io/docs/technical-reference/nuxtjs-prismic}
+ */
+export type ModuleOptions = PrismicModuleOptions
+
+declare module "@nuxt/schema" {
+	interface PublicRuntimeConfig {
+		/** The Prismic Nuxt module options. */
 		prismic: PrismicModuleOptions
 	}
 }
 
-// Module export
+const logger = useLogger("nuxt:prismic")
+
+async function addPrismicClient() {
+	try {
+		const pkg = await readPackage()
+
+		if (
+			!pkg.dependencies?.["@prismicio/client"] &&
+			!pkg.devDependencies?.["@prismicio/client"]
+		) {
+			await addDependency("@prismicio/client")
+			logger.info("Added `@prismicio/client` required peer dependency")
+		}
+	} catch {
+		// noop
+	}
+}
+
 export default defineNuxtModule<PrismicModuleOptions>({
 	meta: {
-		name: '@nuxtjs/prismic',
-		configKey: 'prismic',
-		compatibility: { nuxt: '>=3.7.0' },
+		name,
+		version,
+		configKey: "prismic",
+		compatibility: { nuxt: ">=3.7.0" },
 	},
-	defaults: (nuxt) => {
-		let prismicFiles = {
-			client: '~/app/prismic/client',
-			linkResolver: '~/app/prismic/linkResolver',
-			richTextSerializer: '~/app/prismic/richTextSerializer',
-		}
-
-		let prismicComponentsFiles = {
-			linkRel: '~/app/prismic/linkRel',
-			richTextComponents: '~/app/prismic/richTextComponents',
-			sliceZoneDefaultComponent: '~/app/prismic/sliceZoneDefaultComponent',
+	onInstall() {
+		return addPrismicClient()
+	},
+	onUpgrade(_options: unknown, _nuxt: unknown, previousVersion: string) {
+		const previousMajor = parseInt(previousVersion.split(".")[0]!)
+		if (previousMajor < 4) {
+			return addPrismicClient()
 		}
+	},
+	defaults: (nuxt): Required<PrismicModuleOptions> => {
+		const nuxt3flavor =
+			getNuxtVersion(nuxt).startsWith("3") &&
+			!nuxt.options?.future?.compatibilityVersion
 
-		// Nuxt 4 sets `app` as its `srcDir`, so we're just using the `prismic` folder there.
-		if (
-			nuxt.options?.future?.compatibilityVersion === 4
-			|| getNuxtVersion(nuxt).startsWith('4')
-		) {
-			prismicFiles = {
-				client: '~/prismic/client',
-				linkResolver: '~/prismic/linkResolver',
-				richTextSerializer: '~/prismic/richTextSerializer',
-			}
-			prismicComponentsFiles = {
-				linkRel: '~/prismic/linkRel',
-				richTextComponents: '~/prismic/richTextComponents',
-				sliceZoneDefaultComponent: '~/prismic/sliceZoneDefaultComponent',
+		if (nuxt3flavor) {
+			return {
+				endpoint: "",
+				environment: "",
+				clientConfig: {},
+				client: "~/app/prismic/client",
+				linkResolver: "~/app/prismic/linkResolver",
+				preview: "/preview",
+				toolbar: true,
+				components: {
+					richTextComponents: "~/app/prismic/richTextComponents ",
+				},
 			}
 		}
 
 		return {
-			endpoint: '',
-			environment: '',
+			endpoint: "",
+			environment: "",
+			client: "~/prismic/client",
+			linkResolver: "~/prismic/linkResolver",
 			clientConfig: {},
-			...prismicFiles,
-			injectComponents: true,
-			components: prismicComponentsFiles,
-			preview: '/preview',
+			preview: "/preview",
 			toolbar: true,
-			devtools: true,
+			components: {
+				richTextComponents: "~/prismic/richTextComponents",
+			},
 		}
 	},
-	hooks: {},
 	setup(options, nuxt) {
-		// Expose options through public runtime config
-		nuxt.options.runtimeConfig.public ||= {} as typeof nuxt.options.runtimeConfig.public
-		const moduleOptions: PrismicModuleOptions = defu(nuxt.options.runtimeConfig.public.prismic, options)
-		nuxt.options.runtimeConfig.public.prismic = moduleOptions
-
-		// Runtime dir boilerplate
 		const resolver = createResolver(import.meta.url)
-		if (nuxt.options.devtools && options.devtools) {
-			setupDevToolsUI(nuxt, resolver)
+
+		const moduleOptions: PrismicModuleOptions = defu(
+			nuxt.options.runtimeConfig.public?.prismic,
+			options,
+		)
+
+		exposeRuntimeConfig()
+		transpileDependencies()
+		const ok = proxyUserFiles()
+		if (!ok) return
+		addRuntimePlugins()
+		addAutoImports()
+		addPreviewRoute()
+		extendESLintConfig()
+
+		function exposeRuntimeConfig() {
+			nuxt.options.runtimeConfig.public ||=
+				{} as typeof nuxt.options.runtimeConfig.public
+			nuxt.options.runtimeConfig.public.prismic = moduleOptions
 		}
 
-		// Add runtime user code
-		const proxyUserFileWithUndefinedFallback
-			= (filename: string, path: string, deprecated?: boolean | string): boolean => {
+		function transpileDependencies() {
+			nuxt.options.build.transpile.push(
+				resolver.resolve("runtime"),
+				"@nuxtjs/prismic",
+				"@prismicio/vue",
+			)
+			nuxt.options.vite.optimizeDeps ||= {}
+			nuxt.options.vite.optimizeDeps.exclude ||= []
+			nuxt.options.vite.optimizeDeps.exclude.push("@prismicio/vue")
+		}
+
+		function proxyUserFiles() {
+			const proxyUserFileWithUndefinedFallback = (
+				filename: string,
+				path: string,
+			): boolean => {
 				const resolvedFilename = `prismic/proxy/${filename}.ts`
-				const resolvedPath = path.replace(/^(~~|@@)/, nuxt.options.rootDir).replace(/^(~|@)/, nuxt.options.srcDir)
-				const maybeUserFile = fileExists(resolvedPath, ['js', 'mjs', 'ts', 'vue'])
+				const resolvedPath = path
+					.replace(/^(~~|@@)/, nuxt.options.rootDir)
+					.replace(/^(~|@)/, nuxt.options.srcDir)
+				const maybeUserFile = fileExists(resolvedPath, [
+					"js",
+					"mjs",
+					"ts",
+					"vue",
+				])
 
 				if (maybeUserFile) {
-				// If user file exists, proxy it with vfs
-					logger.info(`Using user-defined \`${filename}\` at \`${maybeUserFile.replace(nuxt.options.srcDir, '~').replace(nuxt.options.rootDir, '~~').replace(/\\/g, '/')}\``)
-					if (deprecated) {
-						logger.warn(`\`${filename}\` is deprecated and will be removed in a future version.${typeof deprecated === 'string' ? `${deprecated}` : ''}`)
-					}
+					// If user file exists, proxy it with vfs
+					logger.info(
+						`Using user-defined \`${filename}\` at \`${maybeUserFile.replace(nuxt.options.srcDir, "~").replace(nuxt.options.rootDir, "~~").replace(/\\/g, "/")}\``,
+					)
 
 					addTemplate({
 						filename: resolvedFilename,
@@ -117,136 +261,190 @@ export default defineNuxtModule<PrismicModuleOptions>({
 					})
 
 					return true
-				}
-				else {
-				// Else provide `undefined` fallback
+				} else {
+					// Else provide `undefined` fallback
 					addTemplate({
 						filename: resolvedFilename,
-						getContents: () => 'export default undefined',
+						getContents: () => "export default undefined",
 					})
 
 					return false
 				}
 			}
 
-		const proxiedUserClient = proxyUserFileWithUndefinedFallback('client', moduleOptions.client!)
-		if (!moduleOptions.endpoint && !proxiedUserClient && !process.env.NUXT_PUBLIC_PRISMIC_ENDPOINT) {
-			logger.warn(`\`endpoint\` option is missing and \`${moduleOptions.client}\` was not found. At least one of them is required for the module to run. Disabling module...`)
-			return
+			const proxiedUserClient = proxyUserFileWithUndefinedFallback(
+				"client",
+				moduleOptions.client!,
+			)
+			if (
+				!moduleOptions.endpoint &&
+				!proxiedUserClient &&
+				!process.env.NUXT_PUBLIC_PRISMIC_ENDPOINT
+			) {
+				logger.warn(
+					`\`endpoint\` option is missing and \`${moduleOptions.client}\` was not found. At least one of them is required for the module to run. Disabling module...`,
+				)
+				return false
+			}
+			proxyUserFileWithUndefinedFallback(
+				"linkResolver",
+				moduleOptions.linkResolver!,
+			)
+			proxyUserFileWithUndefinedFallback(
+				"richTextComponents",
+				moduleOptions.components!.richTextComponents!,
+			)
+
+			return true
+		}
+
+		function addRuntimePlugins() {
+			addPlugin(resolver.resolve("runtime/plugin"))
+			addPlugin(resolver.resolve("runtime/plugin.client"))
 		}
-		proxyUserFileWithUndefinedFallback('linkResolver', moduleOptions.linkResolver!)
-		proxyUserFileWithUndefinedFallback('richTextSerializer', moduleOptions.richTextSerializer!, 'Use `components.richTextComponents` instead.')
-
-		// Components
-		proxyUserFileWithUndefinedFallback('linkRel', moduleOptions.components!.linkRel!)
-		proxyUserFileWithUndefinedFallback('richTextComponents', moduleOptions.components!.richTextComponents!)
-		proxyUserFileWithUndefinedFallback('sliceZoneDefaultComponent', moduleOptions.components!.sliceZoneDefaultComponent!)
-
-		nuxt.options.build.transpile.push(resolver.resolve('runtime'), '@nuxtjs/prismic', '@prismicio/vue')
-		nuxt.options.vite.optimizeDeps ||= {}
-		nuxt.options.vite.optimizeDeps.exclude ||= []
-		nuxt.options.vite.optimizeDeps.exclude.push('@prismicio/vue')
-
-		// Add plugin
-		addPlugin(resolver.resolve('runtime/plugin'))
-		addPlugin(resolver.resolve('runtime/plugin.client'))
-
-		// Add components auto import
-		if (moduleOptions.injectComponents) {
-			[
-				'PrismicEmbed',
-				'PrismicImage',
-				'PrismicLink',
-				'PrismicText',
-				'PrismicRichText',
-				'SliceZone',
-			].forEach((component) => {
+
+		function addAutoImports() {
+			// Components
+			;[
+				"PrismicImage",
+				"PrismicLink",
+				"PrismicText",
+				"PrismicRichText",
+				"PrismicTable",
+				"SliceZone",
+			].forEach((entry) => {
 				addComponent({
-					name: component,
-					export: component,
-					filePath: '@prismicio/vue',
+					name: entry,
+					export: entry,
+					filePath: "@prismicio/vue",
 				})
 			})
-		}
 
-		// Add auto imports
-		const prismicVueAutoImports = Object
-			.keys(prismicVue)
-			.filter(key => key.startsWith('use'))
-			.concat('getSliceComponentProps', 'defineSliceZoneComponents', 'getRichTextComponentProps')
-			.map((key) => {
-				return {
-					name: key,
-					as: key,
-					from: '@prismicio/vue',
-				}
+			// Composables and utils
+			addImports(
+				[
+					"usePrismic",
+					"getSliceComponentProps",
+					"defineSliceZoneComponents",
+					"getRichTextComponentProps",
+					"getTableComponentProps",
+				].map((entry) => ({ name: entry, as: entry, from: "@prismicio/vue" })),
+			)
+			addImports({
+				name: "usePrismicPreview",
+				as: "usePrismicPreview",
+				from: resolver.resolve("runtime/usePrismicPreview"),
 			})
-		addImports(prismicVueAutoImports)
-		addImports({
-			name: 'usePrismicPreview',
-			as: 'usePrismicPreview',
-			from: resolver.resolve('runtime/usePrismicPreview'),
-		})
-
-		// Add preview route
-		if (moduleOptions.preview) {
-			const maybeUserPreviewPage = fileExists(join(nuxt.options.srcDir, nuxt.options.dir.pages, moduleOptions.preview), ['js', 'ts', 'vue'])
-
-			if (maybeUserPreviewPage) {
-				logger.info(`Using user-defined preview page at \`${maybeUserPreviewPage.replace(join(nuxt.options.srcDir), '~').replace(nuxt.options.rootDir, '~~').replace(/\\/g, '/')
-				}\`, available at \`${moduleOptions.preview}\``)
-			}
-			else {
-				logger.info(`Using default preview page, available at \`${moduleOptions.preview}\``)
-
-				extendPages((pages) => {
-					pages.unshift({
-						name: 'prismic-preview',
-						path: moduleOptions.preview as string, // Checked before
-						file: resolver.resolve('runtime/PrismicPreview.vue'),
+		}
+
+		function addPreviewRoute() {
+			if (moduleOptions.preview) {
+				const maybeUserPreviewPage = fileExists(
+					join(
+						nuxt.options.srcDir,
+						nuxt.options.dir.pages,
+						moduleOptions.preview,
+					),
+					["js", "ts", "vue"],
+				)
+
+				if (maybeUserPreviewPage) {
+					logger.info(
+						`Using user-defined preview page at \`${maybeUserPreviewPage
+							.replace(join(nuxt.options.srcDir), "~")
+							.replace(nuxt.options.rootDir, "~~")
+							.replace(
+								/\\/g,
+								"/",
+							)}\`, available at \`${moduleOptions.preview}\``,
+					)
+				} else {
+					logger.info(
+						`Using default preview page, available at \`${moduleOptions.preview}\``,
+					)
+
+					extendPages((pages) => {
+						pages.unshift({
+							name: "prismic-preview",
+							path: moduleOptions.preview as string, // Checked before
+							file: resolver.resolve("runtime/PrismicPreview.vue"),
+						})
 					})
-				})
-			}
+				}
 
-			if (!moduleOptions.toolbar) {
-				logger.warn('`toolbar` option is disabled but `preview` is enabled. Previews won\'t work unless you manually load the toolbar.')
+				if (!moduleOptions.toolbar) {
+					logger.warn(
+						"`toolbar` option is disabled but `preview` is enabled. Previews won't work unless you manually load the toolbar.",
+					)
+				}
 			}
 		}
 
-		// Integrate with @nuxt/eslint
-		// @ts-expect-error 3rd party hook
-		nuxt.hook('eslint:config:addons', (addons: {
-			name: string
-			getConfigs: () => Promise<{ configs: string[] }>
-		}[]) => {
-			addons.push({
-				name: '@nuxtjs/prismic',
-				async getConfigs() {
-					const configPath = resolver.resolve(nuxt.options.rootDir, 'slicemachine.config.json')
-
-					const configs: string[] = []
-
-					try {
-						if (existsSync(configPath)) {
-							const config = JSON.parse(await readFile(configPath, 'utf-8'))
-
-							if (config && 'libraries' in config && Array.isArray(config.libraries)) {
-								configs.push(JSON.stringify({
-									files: config.libraries.map((library: string) => `${library.replace('./', '')}/**/index.vue`),
-									rules: {
-										'vue/multi-word-component-names': 'off',
-									},
-								}))
+		function extendESLintConfig() {
+			nuxt.hook(
+				// @ts-expect-error 3rd party hook
+				"eslint:config:addons",
+				(
+					addons: {
+						name: string
+						getConfigs: () => Promise<{ configs: string[] }>
+					}[],
+				) => {
+					addons.push({
+						name: "@nuxtjs/prismic",
+						async getConfigs() {
+							const configPath = resolver.resolve(
+								nuxt.options.rootDir,
+								"slicemachine.config.json",
+							)
+
+							const configs: string[] = []
+
+							try {
+								if (existsSync(configPath)) {
+									const config = JSON.parse(await readFile(configPath, "utf-8"))
+
+									if (
+										config &&
+										"libraries" in config &&
+										Array.isArray(config.libraries)
+									) {
+										configs.push(
+											JSON.stringify({
+												files: config.libraries.map(
+													(library: string) =>
+														`${library.replace("./", "")}/**/index.vue`,
+												),
+												rules: {
+													"vue/multi-word-component-names": "off",
+												},
+											}),
+										)
+									}
+								}
+							} catch {
+								// noop
 							}
-						}
-					}
-					catch {
-						// noop
-					}
 
-					return { configs }
+							return { configs }
+						},
+					})
 				},
-			})
-		})
+			)
+		}
 	},
 })
+
+function fileExists(path?: string, extensions = ["js", "ts"]): string | null {
+	if (!path) {
+		return null
+	} else if (existsSync(path)) {
+		return path
+	}
+
+	const extension = extensions.find((extension) =>
+		existsSync(`${path}.${extension}`),
+	)
+
+	return extension ? `${path}.${extension}` : null
+}