Feature/enhance inline documentation (#85)

* Improve inline documentation
* npm add @sanity/client

Author: kenjonespizza

nextjs-app/app/[slug]/page.tsx

@@ -1,6 +1,5 @@
 import type { Metadata } from "next";
 import Head from "next/head";
-import { notFound } from "next/navigation";
 
 import PageBuilderPage from "@/app/components/PageBuilder";
 import { sanityFetch } from "@/sanity/lib/live";
@@ -12,20 +11,30 @@ type Props = {
   params: Promise<{ slug: string }>;
 };
 
+/**
+ * Generate the static params for the page.
+ * Learn more: https://nextjs.org/docs/app/api-reference/functions/generate-static-params
+ */
 export async function generateStaticParams() {
   const { data } = await sanityFetch({
     query: pagesSlugs,
+    // // Use the published perspective in generateStaticParams
     perspective: "published",
     stega: false,
   });
   return data;
 }
 
+/**
+ * Generate metadata for the page.
+ * Learn more: https://nextjs.org/docs/app/api-reference/functions/generate-metadata#generatemetadata-function
+ */
 export async function generateMetadata(props: Props): Promise<Metadata> {
   const params = await props.params;
   const { data: page } = await sanityFetch({
     query: getPageQuery,
     params,
+    // Metadata should never contain stega
     stega: false,
   });
 

nextjs-app/app/api/draft-mode/enable/route.ts

@@ -3,6 +3,12 @@ import { defineEnableDraftMode } from "next-sanity/draft-mode";
 import { client } from "@/sanity/lib/client";
 import { token } from "@/sanity/lib/token";
 
+/**
+ * defineEnableDraftMode() is used to enable draft mode. Set the route of this file
+ * as the previewMode.enable option for presentationTool in your sanity.config.ts
+ * Learn more: https://github.com/sanity-io/next-sanity?tab=readme-ov-file#5-integrating-with-sanity-presentation-tool--visual-editing
+ */
+
 export const { GET } = defineEnableDraftMode({
   client: client.withConfig({ token }),
 });

nextjs-app/app/client-utils.ts

@@ -5,6 +5,7 @@ import { toast } from "sonner";
 
 export function handleError(error: unknown) {
   if (isCorsOriginError(error)) {
+    // If the error is a CORS origin error, lets display that specific error.
     const { addOriginUrl } = error;
     toast.error(`Sanity Live couldn't connect`, {
       description: `Your origin is blocked by CORS policy`,

nextjs-app/app/components/BlockRenderer.tsx

@@ -22,6 +22,9 @@ const Blocks: BlocksType = {
   infoSection: Info,
 };
 
+/**
+ * Used by the <PageBuilder>, this component renders a the component that matches the block type.
+ */
 export default function BlockRenderer({ block, index }: BlockProps) {
   // Block does exist
   if (typeof Blocks[block._type] !== "undefined") {

nextjs-app/app/components/Onboarding.tsx

@@ -6,19 +6,10 @@
  */
 
 import Link from "next/link";
-import { useSyncExternalStore } from "react";
 
 import { studioUrl } from "@/sanity/lib/api";
 
-const emptySubscribe = () => () => {};
-
 export default function Onboarding() {
-  const target = useSyncExternalStore(
-    emptySubscribe,
-    () => (window.top === window ? undefined : "_blank"),
-    () => "_blank"
-  );
-
   return (
     <div className="max-w-2xl mx-auto grid grid-flow-row gap-6 py-12 text-center bg-red-500 text-white rounded-lg p-8">
       <svg
@@ -120,12 +111,6 @@ const OnboardingMessage = ({ message, link }: OnboardingMessageProps) => {
 };
 
 export function PageOnboarding() {
-  const target = useSyncExternalStore(
-    emptySubscribe,
-    () => (window.top === window ? undefined : "_blank"),
-    () => "_blank"
-  );
-
   return (
     <div className="max-w-2xl mx-auto grid grid-flow-row gap-6 py-12 text-center bg-red-500 text-white rounded-lg p-8">
       <svg

nextjs-app/app/components/PageBuilder.tsx

@@ -8,6 +8,9 @@ type PageBuilderPageProps = {
   page: Page;
 };
 
+/**
+ * The PageBuilder component is used to render the blocks from the `pageBuilder` field in the Page type in your Sanity Studio.
+ */
 export default function PageBuilder({ page }: PageBuilderPageProps) {
   if (page?.pageBuilder && page.pageBuilder.length > 0) {
     return (

nextjs-app/app/components/ResolvedLink.tsx

@@ -13,6 +13,7 @@ export default function ResolvedLink({
   children,
   className,
 }: ResolvedLinkProps) {
+  // resolveLink() is used to determine the type of link and return the appropriate URL.
   const resolvedLink = linkResolver(link);
 
   if (typeof resolvedLink === "string") {

nextjs-app/app/layout.tsx

@@ -16,6 +16,10 @@ import { settingsQuery } from "@/sanity/lib/queries";
 import { resolveOpenGraphImage } from "@/sanity/lib/utils";
 import { handleError } from "./client-utils";
 
+/**
+ * Generate metadata for the page.
+ * Learn more: https://nextjs.org/docs/app/api-reference/functions/generate-metadata#generatemetadata-function
+ */
 export async function generateMetadata(): Promise<Metadata> {
   const { data: settings } = await sanityFetch({
     query: settingsQuery,
@@ -64,13 +68,16 @@ export default async function RootLayout({
     <html lang="en" className={`${inter.variable} bg-white text-black`}>
       <body>
         <section className="min-h-screen pt-24">
+          {/* The <Toaster> component is responsible for rendering toast notifications used in /app/client-utils.ts and /app/components/DraftModeToast.tsx */}
           <Toaster />
           {isDraftMode && (
             <>
               <DraftModeToast />
+              {/*  Enable Visual Editing, only to be rendered when Draft Mode is enabled */}
               <VisualEditing />
             </>
           )}
+          {/* The <SanityLive> component is responsible for making all sanityFetch calls in your application live, so should always be rendered. */}
           <SanityLive onError={handleError} />
           <Header />
           <main className="">{children}</main>

nextjs-app/app/posts/[slug]/page.tsx

@@ -15,15 +15,24 @@ type Props = {
   params: Promise<{ slug: string }>;
 };
 
+/**
+ * Generate the static params for the page.
+ * Learn more: https://nextjs.org/docs/app/api-reference/functions/generate-static-params
+ */
 export async function generateStaticParams() {
   const { data } = await sanityFetch({
     query: postPagesSlugs,
+    // Use the published perspective in generateStaticParams
     perspective: "published",
     stega: false,
   });
   return data;
 }
 
+/**
+ * Generate metadata for the page.
+ * Learn more: https://nextjs.org/docs/app/api-reference/functions/generate-metadata#generatemetadata-function
+ */
 export async function generateMetadata(
   props: Props,
   parent: ResolvingMetadata
@@ -32,6 +41,7 @@ export async function generateMetadata(
   const { data: post } = await sanityFetch({
     query: postQuery,
     params,
+    // Metadata should never contain stega
     stega: false,
   });
   const previousImages = (await parent).openGraph?.images || [];

nextjs-app/package-lock.json

@@ -10,6 +10,7 @@
     "typegen": "sanity typegen generate"
   },
   "dependencies": {
+    "@sanity/client": "^6.22.5",
     "@sanity/image-url": "^1.1.0",
     "@tailwindcss/typography": "^0.5.15",
     "@types/node": "^20.14.13",