Improve documentation

examples/with-apollo/apolloClient.js

@@ -3,7 +3,7 @@ import { InMemoryCache } from 'apollo-cache-inmemory'
 import { HttpLink } from 'apollo-link-http'
 import fetch from 'isomorphic-unfetch'
 
-export default function createApolloClient(apolloState, ctx) {
+export default function createApolloClient(initialState, ctx) {
   // The `ctx` will only be present on the server.
   // use it to extract auth headers (ctx.req) or similar.
   return new ApolloClient({
@@ -13,6 +13,6 @@ export default function createApolloClient(apolloState, ctx) {
       credentials: 'same-origin', // Additional fetch() options like `credentials` or `headers`
       fetch,
     }),
-    cache: new InMemoryCache().restore(apolloState),
+    cache: new InMemoryCache().restore(initialState),
   })
 }

examples/with-apollo/lib/apollo.js

@@ -4,13 +4,21 @@ import Head from 'next/head'
 import { ApolloProvider } from '@apollo/react-hooks'
 import createApolloClient from '../apolloClient'
 
+// On the client we store the apollo client in the following variable
+// this prevents the client from reinitializing between page transitions.
 let globalApolloClient = null
 
-// We expose this function so we are able to use
-// apolloClient inside getStaticProps, getStaticPaths or getServerProps
-export const ensureApolloClient = ctx => {
+/**
+ * Installes the apollo client on NextPageContext
+ * or NextAppContext. Useful if you want to use apolloClient
+ * inside getStaticProps, getStaticPaths or getServerProps
+ * @param {NextPageContext | NextAppContext} ctx
+ */
+export const initOnContext = ctx => {
   const inAppContext = Boolean(ctx.ctx)
 
+  // We consider installing `withApollo({ ssr: true })` on global App level
+  // as antipattern since it disables project wide Automatic Static Optimization.
   if (process.env.NODE_ENV === 'development') {
     if (inAppContext) {
       console.warn(
@@ -41,21 +49,43 @@ export const ensureApolloClient = ctx => {
   return ctx
 }
 
+/**
+ * Always creates a new apollo client on the server
+ * Creates or reuses apollo client in the browser.
+ * @param  {NormalizedCacheObject} initialState
+ * @param  {NextPageContext} ctx
+ */
+const initApolloClient = (initialState, ctx) => {
+  // Make sure to create a new client for every server-side request so that data
+  // isn't shared between connections (which would be bad)
+  if (typeof window === 'undefined') {
+    return createApolloClient(initialState, ctx)
+  }
+
+  // Reuse client on the client-side
+  if (!globalApolloClient) {
+    globalApolloClient = createApolloClient(initialState, ctx)
+  }
+
+  return globalApolloClient
+}
+
 /**
  * Creates a withApollo HOC
  * that provides the apolloContext
  * to a next.js Page or AppTree.
+ * @param  {Object} withApolloOptions
+ * @param  {Boolean} [withApolloOptions.ssr=false]
+ * @returns {(PageComponent: ReactNode) => ReactNode}
  */
-export const withApollo = ({ ssr } = {}) => PageComponent => {
+export const withApollo = ({ ssr = false } = {}) => PageComponent => {
   const WithApollo = ({ apolloClient, apolloState, ...pageProps }) => {
-    // Called by:
-    // - getDataFromTree => apolloClient
-    // - next.js ssr => apolloClient
-    // - next.js csr => apolloState
     let client
     if (apolloClient) {
+      // Happens on: getDataFromTree & next.js ssr
       client = apolloClient
     } else {
+      // Happens on: next.js csr
       client = initApolloClient(apolloState, undefined)
     }
 
@@ -70,14 +100,13 @@ export const withApollo = ({ ssr } = {}) => PageComponent => {
   if (process.env.NODE_ENV !== 'production') {
     const displayName =
       PageComponent.displayName || PageComponent.name || 'Component'
-
     WithApollo.displayName = `withApollo(${displayName})`
   }
 
   if (ssr || PageComponent.getInitialProps) {
     WithApollo.getInitialProps = async ctx => {
       const inAppContext = Boolean(ctx.ctx)
-      const { apolloClient } = ensureApolloClient(ctx)
+      const { apolloClient } = initOnContext(ctx)
 
       // Run wrapped getInitialProps methods
       let pageProps = {}
@@ -99,7 +128,8 @@ export const withApollo = ({ ssr } = {}) => PageComponent => {
         // Only if dataFromTree is enabled
         if (ssr && AppTree) {
           try {
-            // Run all GraphQL queries
+            // Import `@apollo/react-ssr` dynamically.
+            // We don't want to have this in our client bundle.
             const { getDataFromTree } = await import('@apollo/react-ssr')
 
             // Since AppComponents and PageComponents have different context types
@@ -111,8 +141,11 @@ export const withApollo = ({ ssr } = {}) => PageComponent => {
               props = { pageProps: { ...pageProps, apolloClient } }
             }
 
-            // Takes React AppTree, determine which queries are needed to render,
-            // then fetche them all.
+            // Take the Next.js AppTree, determine which queries are needed to render,
+            // and fetch them. This method can be pretty slow since it renders
+            // your entire AppTree once for every query. Check out apollo fragments
+            // if you want to reduce the number of rerenders.
+            // https://www.apollographql.com/docs/react/data/fragments/
             await getDataFromTree(<AppTree {...props} />)
           } catch (error) {
             // Prevent Apollo Client GraphQL errors from crashing SSR.
@@ -127,36 +160,16 @@ export const withApollo = ({ ssr } = {}) => PageComponent => {
         }
       }
 
-      // Extract query data from the Apollo store
-      const apolloState = apolloClient.cache.extract()
-
       return {
         ...pageProps,
-        apolloState,
+        // Extract query data from the Apollo store
+        apolloState: apolloClient.cache.extract(),
+        // Provide the client for ssr. As soon as this payload
+        // gets JSON.stringified it will remove itself.
         apolloClient: ctx.apolloClient,
       }
     }
   }
 
   return WithApollo
 }
-
-/**
- * Always creates a new apollo client on the server
- * Creates or reuses apollo client in the browser.
- * @param  {Object} initialState
- */
-const initApolloClient = (initialState, ctx) => {
-  // Make sure to create a new client for every server-side request so that data
-  // isn't shared between connections (which would be bad)
-  if (typeof window === 'undefined') {
-    return createApolloClient(initialState, ctx)
-  }
-
-  // Reuse client on the client-side
-  if (!globalApolloClient) {
-    globalApolloClient = createApolloClient(initialState, ctx)
-  }
-
-  return globalApolloClient
-}

examples/with-apollo/pages/about.js

@@ -1,7 +1,7 @@
 import App from '../components/App'
 import Header from '../components/Header'
 
-export default () => (
+const AboutPage = () => (
   <App>
     <Header />
     <article>
@@ -41,3 +41,5 @@ export default () => (
     </article>
   </App>
 )
+
+export default AboutPage

examples/with-apollo/pages/client-only.js

@@ -26,5 +26,4 @@ const ClientOnlyPage = props => (
   </App>
 )
 
-// Disable apollo ssr fetching in favour of automatic static optimization
 export default withApollo()(ClientOnlyPage)

examples/with-apollo/pages/index.js

@@ -5,7 +5,7 @@ import Submit from '../components/Submit'
 import PostList from '../components/PostList'
 import { withApollo } from '../lib/apollo'
 
-const IndexPage = props => (
+const IndexPage = () => (
   <App>
     <Header />
     <InfoBox>
@@ -26,4 +26,4 @@ const IndexPage = props => (
   </App>
 )
 
-export default withApollo()(IndexPage)
+export default withApollo({ ssr: true })(IndexPage)