Merge pull request #51 from jakala-na/fix/content-source-maps

fix(content-source-maps): Improve content source maps docs and usage.…

README.md

@@ -15,28 +15,37 @@ The starterkit's cornerstone is our data-fetching solution and it's typesafety.
 
 ## Getting Started
 
-Clone the repo of course ;)
+1. This project is a template, feel free to either clone it (to preserve project history) or use click "Use this template" to create a repository with a single init commit.
+   As soon as you have a repository, clone it locally
+2. Install dependencies with:
 
-### Contentful access
+```
+yarn install
+```
 
-To develop locally, you will want to connect to a Contentful instance that has the same data model as we use to develop, there are 2 ways to do that:
+3. Setup Contenful access
+   To develop locally, you will want to connect to a Contentful instance that has the same data model as we use to develop, there are 2 ways to do that:
 
-1. You could get access to an existing space that follows Contentful Marketing Template content model, for example a collegue could share his space with you
-2. You could create your own space with https://www.contentful.com/starter-templates/marketing-website/. Keep in mind, new templates today can only be deployed on brand new Contentful accounts, so you might have to create a new account with a new email to do that, but this shouldn't be a problem, as it's free.
+- You could get access to an existing space that follows Contentful Marketing Template content model, for example a collegue could share his space with you
+- You could create your own space with https://www.contentful.com/starter-templates/marketing-website/. Keep in mind, new templates today can only be deployed on brand new Contentful accounts, so you might have to create a new account with a new email to do that, but this shouldn't be a problem, as it's free.
 
-### Configure environment
+You will want to get a CDA and CPA API keys by using this [guide](https://www.contentful.com/developers/docs/references/authentication/#api-keys-in-the-contentful-web-app)
+
+4. Configure environment
 
 Create .env.local in root directory of the repo with the following contents:
 
 ```
 CONTENTFUL_SPACE=<space id>
 CONTENTFUL_DELIVERY_API=<delivery api key>
-CONTENTFUL_PREVIEW_API=<preview api key>****
+CONTENTFUL_PREVIEW_API=<preview api key>
 CONTENTFUL_ENVIRONMENT=master
 CONTENTFUL_PREVIEW_SECRET=secret
+# Enable or disable Content Source Maps, see https://www.contentful.com/developers/docs/tools/vercel/content-source-maps-with-vercel/
+CONTENTFUL_USE_CONTENT_SOURCE_MAPS=true
 ```
 
-### Dev Server
+5. Run Dev Server
 
 ```bash
 yarn dev
@@ -74,6 +83,15 @@ yarn generate:output
 This command will also run `gql.tada turbo` which will generate a cache file that should also be commited. This cache file will speed up inference for new users who just checked out a new branch.
 More info [here](https://gql-tada.0no.co/devlog/2024-04-15)
 
+### Content Source Maps in Live Preview and on Vercel
+
+Contentful has released a new live-preview API compatible content source maps spec, you can read more [here](https://www.contentful.com/developers/docs/tools/vercel/content-source-maps-with-vercel/). This implementation enabled effortless inspector mode annotations in Live Preview, as well as full Edit Mode support on Vercel. Unfortunately for some folks testing the starterkit on FREE plan, this feature is only available on Pro+. While Content Source Maps enables Visual Editing on Vercel, Visual Editing is also only available in Pro+. If you're testing the starterkit and would like to not use content source maps, you are free to opt out by:
+
+1. Settings `CONTENTFUL_USE_CONTENT_SOURCE_MAPS=false` in .env.local or in Vercel
+2. Removing `@contentSourceMaps` directive from GraphQL queries
+
+** Note: @contentSourceMaps ideally could be added conditionally, but gql.tada prevents any dynamic strings from being typed TadaDocumentNode. In future we will add the @contentSourceMaps directive to all queries in urql exchange.**
+
 ## NextJS Docs
 
 To learn more about Next.js, take a look at the following resources:

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

@@ -1,13 +1,14 @@
 import { draftMode } from 'next/headers';
+import { notFound } from 'next/navigation';
 
-import { encodeGraphQLResponse } from '@contentful/content-source-maps';
 import { graphql } from 'gql.tada';
 
 import { ComponentRenderer } from '#/components/component-renderer';
 import DebugMode from '#/components/debug-mode/debug-mode';
 import { ComponentDuplexFieldsFragment } from '#/components/duplex-ctf/duplex-ctf';
 import { ComponentHeroBannerFieldsFragment } from '#/components/hero-banner-ctf/hero-banner-ctf';
 import { ComponentTopicBusinessInfoFieldsFragment } from '#/components/topic-business-info/topic-business-info';
+import { addContentSourceMaps } from '#/lib/contentSourceMaps';
 import { graphqlClient } from '#/lib/graphqlClient';
 
 const getPage = async (slug: string, locale: string, preview = false) => {
@@ -38,14 +39,8 @@ const getPage = async (slug: string, locale: string, preview = false) => {
     slug,
   });
 
-  const formattedData = preview
-    ? encodeGraphQLResponse({
-        data: response.data,
-        extensions: response.extensions,
-      })
-    : response;
-
-  return formattedData?.data?.pageCollection?.items?.[0];
+  const processedResponse = addContentSourceMaps(response);
+  return processedResponse?.data?.pageCollection?.items?.[0];
 };
 
 const getPageSlugs = async () => {
@@ -81,6 +76,10 @@ export default async function LandingPage({ params }: { params: { slug: string[]
 
   const pageData = await getPage(slug, 'en-US', isDraftMode);
 
+  if (!pageData) {
+    notFound();
+  }
+
   const topComponents = pageData?.topSectionCollection?.items;
   const pageContent = pageData?.pageContent;
 

app/layout.tsx

@@ -11,6 +11,7 @@ import { graphql } from 'gql.tada';
 import { ContentfulPreviewProvider } from '#/components/contentful-preview-provider';
 import { NavigationFieldsFragment } from '#/components/navigation';
 import { SiteHeader } from '#/components/site-header';
+import { isContentSourceMapsEnabled } from '#/lib/contentSourceMaps';
 import { fontSans } from '#/lib/fonts';
 import { cn } from '#/lib/utils';
 
@@ -46,7 +47,7 @@ export default async function RootLayout({ children }: { children: React.ReactNo
       */}
       <head />
       <body className={cn('min-h-screen bg-background font-sans antialiased', fontSans.variable)}>
-        <ContentfulPreviewProvider isDraftMode={isDraftMode}>
+        <ContentfulPreviewProvider isDraftMode={isDraftMode} isContentSourceMapsEnabled={isContentSourceMapsEnabled}>
           <div className="relative flex min-h-screen flex-col">
             <SiteHeader navigationData={layoutData.data?.navigationMenuCollection} />
             <div className="flex-1">{children}</div>

components/contentful-preview-provider/contentful-preview-provider.tsx

@@ -2,14 +2,22 @@
 
 import { ContentfulLivePreviewProvider } from '@contentful/live-preview/react';
 
-const ContentfulPreviewProvider = ({ isDraftMode, children }: { isDraftMode: boolean; children: any }) => {
+const ContentfulPreviewProvider = ({
+  isDraftMode,
+  isContentSourceMapsEnabled,
+  children,
+}: {
+  isDraftMode: boolean;
+  isContentSourceMapsEnabled: boolean;
+  children: any;
+}) => {
   const previewActive = isDraftMode;
   return (
     <ContentfulLivePreviewProvider
       locale={'en-US'}
       enableInspectorMode={previewActive}
       enableLiveUpdates={previewActive}
-      experimental={{ ignoreManuallyTaggedElements: true }}
+      experimental={{ ignoreManuallyTaggedElements: isContentSourceMapsEnabled }}
     >
       {children}
     </ContentfulLivePreviewProvider>

gql/graphql-cache.d.ts

@@ -19,6 +19,7 @@ declare module 'gql.tada' {
         pageCollection: {
           items: ({
             pageContent:
+              | { __typename?: 'ComponentDuplex' | undefined }
               | { __typename?: 'ComponentProductTable' | undefined }
               | {
                   [$tada.fragmentRefs]: { ComponentTopicBusinessInfo: 'TopicBusinessInfo' };
@@ -130,6 +131,7 @@ declare module 'gql.tada' {
     '\n  fragment PageLinkFields on Page {\n    __typename\n    slug\n    sys {\n      id\n    }\n    pageName\n    pageContent(locale: $locale, preview: $preview) {\n      ... on Entry {\n        __typename\n        sys {\n          id\n        }\n      }\n    }\n  }\n': TadaDocumentNode<
       {
         pageContent:
+          | { sys: { id: string }; __typename: 'ComponentDuplex' }
           | { sys: { id: string }; __typename: 'ComponentProductTable' }
           | { sys: { id: string }; __typename: 'TopicBusinessInfo' }
           | { sys: { id: string }; __typename: 'TopicProduct' }
@@ -149,6 +151,7 @@ declare module 'gql.tada' {
           links: {
             entries: {
               block: (
+                | { __typename?: 'ComponentDuplex' | undefined }
                 | { __typename?: 'ComponentProductTable' | undefined }
                 | { __typename?: 'TopicProduct' | undefined }
                 | { __typename?: 'Accordion' | undefined }
@@ -162,7 +165,6 @@ declare module 'gql.tada' {
                 | { __typename?: 'NavigationMenu' | undefined }
                 | { __typename?: 'AccordionItem' | undefined }
                 | { __typename?: 'BasicPage' | undefined }
-                | { __typename?: 'ComponentDuplex' | undefined }
                 | { __typename?: 'ComponentHeroBanner' | undefined }
                 | { __typename?: 'EditorTest' | undefined }
                 | { __typename?: 'FooterMenu' | undefined }