GraphQL Integration and Rendering
Schema package
nautical-commerce/graphql-schema is a publicly available package that contains the Nautical API schema. The package is versioned for each release, so it's important to keep it up to date.
Regularly updating this package ensures that you have the latest version of the schema. By doing so, the reference storefront can validate your GraphQL queries and types against the official schema, reducing the chances of encountering errors.
Codegen tool
The reference storefront utilizes graphql-codegen to automatically generate utility code and an SDK for accessing the GraphQL API using graphql-request.
The code generation is based on the GraphQL schema and query documents. To configure the codegen tool, you can modify codegen.ts in the root folder.
GraphQL types and SDK are generated to the src/graphql/_generated folder. The generated code includes TypeScript types for the GraphQL schema, as well as hooks and components for query execution.
The NEXT_PUBLIC_API_URI environment variable must be set appropriately to fetch the schema from the GraphQL API endpoint.
Watch mode
While in development, you can run the codegen tool in watch mode to regenerate the SDK and types as files are changed:
yarn generate:types -w
SDK configuration
While graphql-codegen outputs the generated SDK to src/graphql/_generated/sdk.ts, you should be using the SDK exported in src/utils/graphqlSdk.ts
The graphqlSdk.ts file handles creating the client used to actually fetch data from the API using the methods generated from the codegen.
Backend-for-frontend API
Some GraphQL requests are handled through the backend-for-frontend (BFF) pattern, which involves creating a backend service specifically tailored to the requirements of the storefront.
The reference storefront employs the BFF pattern to simplify certain aspects of client-side data fetching and to handle specific requirements such as cookies.
BFF routes
The BFF route handlers are located in the src/pages/api. The client-side components can use react-query to fetch data through these BFF endpoints instead of hitting the external API directly.
For instance, functionalities like Checkout, Authentication, Wishlists, and Payments are facilitated through BFF routes, optimizing interactions with backend services.
Rendering process
The reference storefront uses server-side rendering (SSR) for most pages, with client-side data fetching for components that require data after the initial page loading.
Server-side rendering
SSR, or server-side rendering, involves the server generating HTML for each page request, unlike Client-Side Rendering where the browser uses JavaScript to dynamically create content. SSR enhances initial page load speed and is SEO-friendly, as it's easier for search engines to index.
In the reference storefront, Next.js allows for SSR through the getServerSideProps async function, fetching data server-side before rendering. This sends the client a pre-filled page, which is then "hydrated" into an interactive React app.
Client-side data fetching
While SSR handles initial page loads, some components, such as those managing search and filtering, rely on client-side data fetching. The project employs libraries like react-query and graphql-request, as well as BFF API routes, to manage client-side data fetching.
Client-side data fetching retrieves data from APIs or other sources directly in the browser after the initial page load. This enables dynamic content updates without reloading the entire page.
For example, when users apply filters to product listings or execute searches, the application fetches data client-side to update content without a full page refresh.