From 25e93f452b351a5e3c7551f25adbcd71df64bedc Mon Sep 17 00:00:00 2001 From: Nate Archer <12628964+narcher7@users.noreply.github.com> Date: Fri, 5 Nov 2021 10:26:47 -0500 Subject: [PATCH 01/12] Grammar Dev Env Setup (#630) --- docs/tutorial/dev-env-setup.mdx | 39 +++++++++++++++++---------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/docs/tutorial/dev-env-setup.mdx b/docs/tutorial/dev-env-setup.mdx index 8905907bd..10717083e 100644 --- a/docs/tutorial/dev-env-setup.mdx +++ b/docs/tutorial/dev-env-setup.mdx @@ -6,19 +6,19 @@ description: Setting up your development environment with this guide will make y # Development Environment Setup -Setting up your development environment with this guide will make your experience developing with Faust.js fast and efficient. +Use this guide to make your experience developing with Faust.js fast and efficient. ## WordPress Site -As you may know, WordPress is a content management system (CMS) that allows you to create a website with themes/plugins/etc. It is one of the most popular CMSs in the world, and it is used by over 40% of all websites. +As you may know, WordPress is a content management system (CMS) that allows you to create a website with themes/plugins/etc. It is one of the most popular CMSs globally, used by over 40% of all websites. ### What is Headless? -Up until recently, WordPress was used to build monolithic websites. Meaning, the frontend and backend were both tightly coupled via themes and plugins. This has started to change recently with the popularity of Headless. +Up until recently, WordPress could only build monolithic websites. Meaning, the frontend, and backend were both tightly coupled via themes and plugins. Headless shifts away from a monolithic approach. -Headless is a term used when the frontend is detached from the backend. In a more specific sense, when WordPress is used as a backend (headless CMS), while the frontend uses a more modern framework, like React. +Headless is a term used when the frontend detaches from the backend. WordPress is used as a backend (headless CMS) in a more specific sense, while the frontend uses a more modern framework, like React. -Headless allows designers and developers to use modern frameworks they are familiar with to build fast and reliable frontend experiences with a backend that is easy and familiar. +Headless allows designers and developers to use modern frameworks they are familiar with to build fast and reliable frontend experiences with an easy and standard backend. ### Setting up WordPress for Headless @@ -26,7 +26,7 @@ To setup WordPress for headless, follow the [Setting Up WordPress guide for Faus ## Languages & Tooling -If you are coming from a WordPress background, you may be familiar with doing everything in [PHP](https://php.net). +If you come from a WordPress background, you may be familiar with doing everything in [PHP](https://php.net). The frontend landscape has embraced JavaScript/TypeScript as the languages of choice, so it will be helpful to know what these languages are and how they play a part in developing headless WordPress sites. @@ -34,21 +34,21 @@ The frontend landscape has embraced JavaScript/TypeScript as the languages of ch To quote [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/First_steps/What_is_JavaScript): -> JavaScript is a scripting or programming language that allows you to implement complex features on web pages — every time a web page does more than just sit there and display static information for you to look at — displaying timely content updates, interactive maps, animated 2D/3D graphics, scrolling video jukeboxes, etc. — you can bet that JavaScript is probably involved. It is the third layer of the layer cake of standard web technologies, two of which (HTML and CSS) we have covered in much more detail in other parts of the Learning Area. +> JavaScript is a scripting or programming language that allows you to implement complex features on web pages. Every time a web page does display static information for you to look such as showing timely content updates, interactive maps, animated 2D/3D graphics, scrolling video jukeboxes, etc. — you can bet that JavaScript is probably involved. It is the third layer of the layer cake of standard web technologies, two of which (HTML and CSS) we have covered in much more detail in other parts of the Learning Area. -JavaScript is used in almost all frontend frameworks like React, Vue, Angular, etc, and is the language Faust.js is written in. +JavaScript shows up in almost all frontend frameworks like React, Vue, Angular, etc., and Faust.js. -There is no need to install JavaScript, it is already bundled with your browser. +There is no need to install JavaScript since it comes bundled in all modern browsers. If you are new to JavaScript, check out the [JavaScript basics on MDN Web Docs.](https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/JavaScript_basics) ### TypeScript -JavaScript is what is known as a loosely typed language. This means that you don't have to specify the type of a variable. While this is convenient, it can also lead to bugs and errors that you may not know about until runtime. +JavaScript is a loosely typed language, which means you don't have to specify the type of variable. While this is convenient, it can also lead to bugs and errors that you may not know about until runtime. -TypeScript is a typed superset of JavaScript that adds compile-time type checking. This means that you can catch errors at compile time rather than runtime. +TypeScript is a typed superset of JavaScript that adds compile-time type checking. You can catch errors at compile time rather than runtime. -Although it is not required to know TypeScript, it is highly recommended as it makes the developer experience, especially when using Faust.js, a whole lot better. +Although it is not required to know TypeScript, we recommend it, as it makes the developer experience, especially when using Faust.js, much better. ## Node.js & NPM @@ -56,11 +56,11 @@ In the world of JavaScript development, you may see a lot of talk about Node.js ### Node.js -Node.js is a JavaScript runtime that allows you to run JavaScript on the server. You may see this in JavaScript frameworks like [Next.js](https://nextjs.org/), which provide server side functionality. +Node.js is a JavaScript runtime that allows you to run JavaScript on the server. You may see this in JavaScript frameworks like [Next.js](https://nextjs.org/), providing server-side functionality. ### NPM -[NPM](https://npmjs.org) is a package manager for JavaScript. It is used to install JavaScript packages, such as Faust.js, React, etc. +[NPM](https://npmjs.org) is a package manager for JavaScript used to install JavaScript packages, such as Faust.js, React, etc. ### Installation @@ -70,7 +70,7 @@ You can download the installer for Node.js (and NPM) via https://nodejs.org/en/d ## React -React is a JavaScript library for building user interfaces. It is component based, meaning that you can break down your UI into smaller components that can be reused. +React is a JavaScript library for building user interfaces. It is component-based, meaning that you can break down your UI into smaller components to reuse. React is currently the world's most popular JavaScript framework, with about 60% of the market share. With this level of popularity comes plenty of great resources to learn React. We recommend viewing the [React docs to get started.](https://reactjs.org/docs/getting-started.html) @@ -78,9 +78,9 @@ React is currently the world's most popular JavaScript framework, with about 60% GraphQL is a query language for APIs. In Faust.js, it is used to define the data schema of WordPress. -The key distinction between GraphQL and a REST API, is that GraphQL is a query language, meaning that you can ask for as much or as little of the data as you want. Whereas with REST, you are stuck with a fixed set of data. +The critical distinction between GraphQL and a REST API is that GraphQL is a query language, meaning that you can ask for as much or as little of the data as you want. Whereas with REST, you are stuck with a fixed set of data. -For an example, I may want to request a list of WordPress posts, but I only want the title and content. In a GraphQL API, I can specify these two fields as the only pieces of data to fetch, and I'll get *just* that data back. In a REST API, I am unable to specify that level of granularity, and I'm left with requesting more data than I may need. +For example, you may want to request a list of WordPress posts, but I only want the title and content. In a GraphQL API, you can specify these two fields as the only pieces of data to fetch, and you get that data back. In a REST API, you cannot determine that level of granularity, and you're left with requesting more data than you may need. To learn more about GraphQL, check out the [GraphQL docs](https://graphql.org/learn/). @@ -94,7 +94,7 @@ To get started with Git, [download and install the latest release for your OS.]( ## VS Code -Finally, we recommend you use [VS Code](https://code.visualstudio.com/) for your code editor. VS Code has powerful intellisense, a built-in debugger, and a lot of other features that make it a great editor for JavaScript development. +Finally, we recommend you use [VS Code](https://code.visualstudio.com/) for your code editor. VS Code has powerful IntelliSense, a built-in debugger, and many other features that make it a great editor for JavaScript development. In addition, there are a few extensions that will make your experience building headless WordPress sites a lot easier: @@ -104,8 +104,9 @@ In addition, there are a few extensions that will make your experience building ## On Windows -If you are using Windows we suggest you install [Powershell Core](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell-core-on-windows?view=powershell-7.1) and [Windows Terminal](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701) and then use Windows Terminal to run your command line commands. These two tools provide an experience that closely resembles the command line experience you would see in a Linux environment, so it will make things easier for you. +If you are using Windows, we suggest you install [Powershell Core](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell-core-on-windows?view=powershell-7.1) and [Windows Terminal](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701) and then use Windows Terminal to run your command line commands. These two tools provide an experience that closely resembles the command line experience you would see in a Linux environment, making things easier for you. ## What's Next? The next step is to setup your [basic headless site](./basic-headless-site). + From 8d9bc5f60cdc0be5b6d3137e1603789060d93772 Mon Sep 17 00:00:00 2001 From: Nate Archer <12628964+narcher7@users.noreply.github.com> Date: Fri, 5 Nov 2021 10:27:14 -0500 Subject: [PATCH 02/12] Grammar edits to basic headless site (#629) --- docs/tutorial/basic-headless-site.mdx | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/tutorial/basic-headless-site.mdx b/docs/tutorial/basic-headless-site.mdx index e70af9c49..1354d297d 100644 --- a/docs/tutorial/basic-headless-site.mdx +++ b/docs/tutorial/basic-headless-site.mdx @@ -1,42 +1,42 @@ --- slug: /tutorial/basic-headless-site title: Create A Basic Headless WordPress Site -description: In this tutorial, we'll walk you through the process of creating a basic headless WordPress site using Next.js and Local +description: In this tutorial, we'll walk you through the process of creating a basic headless WordPress site using Next.js and Local. --- -In the previous tutorial, we setup our development environment to create JavaScript/TypeScript apps efficiently. +In the previous tutorial, we set up our development environment to create JavaScript/TypeScript apps efficiently. -Now, we are going to create our frontend web app using Next.js, and spin up an instance of WordPress. +Now, we will create our frontend web app using Next.js, and spin up an instance of WordPress. ## Create a Next.js App -Next.js offers a handy CLI tool called `create-next-app` that will help us create a basic Next.js app. +Next.js offers a handy CLI tool called `create-next-app` to help us create a basic Next.js app. To get started, run the following command: -```bash +"`bash npx create-next-app my-app ``` -You may be asked to install `create-next-app` if you haven't already. If you are prompted, enter `y` to continue. +If prompted to `create-next-app`, enter `y' to continue. -Great! Your app has been created. However, it's not quite ready for TypeScript yet. Let's do that now. +Great! You've deployed your app! However, it's not quite ready for TypeScript yet. Let's do that now. ### Setup TypeScript -Start by `cd`ing into your app directory: +Start by `cd'ing into your app directory: -```bash +"`bash cd my-app ``` Now, run: -```bash +"`bash touch tsconfig.json ``` -This will create your [TypeScript config file.](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) +This command creates your [TypeScript config file.](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) Now, let's install TypeScript and our dependencies. @@ -44,7 +44,7 @@ Now, let's install TypeScript and our dependencies. npm install --save-dev typescript @types/react ``` -Once the dependencies are installed, you can run `npm run dev` to start the development server. Doing this will automatically generate the settings needed for `tsconfig.json`. +Once the dependencies are installed, run `npm run dev` to start the development server. Doing this will automatically generate the settings needed for `tsconfig.json`. Now, convert your existing pages to TypeScript: @@ -70,7 +70,7 @@ Your Next.js site is now ready for TypeScript! Let's move on to WordPress. Now that we have created a Next.js app, we can create a WordPress site. We use [Local](https://localwp.com) to spin up instances of WordPress locally. -Start by downloading and installing Local from https://localwp.com. Once, installed, click the `+` button in the bottom left corner of the screen. +Download and install Local from https://localwp.com. Once installed, click the `+` button in the bottom left corner of the screen. Date: Fri, 5 Nov 2021 11:53:49 -0700 Subject: [PATCH 03/12] Breakout Hooks Docs into Seperate Pages (#632) * doc: (#519) adding examples for getStaticPaths * Update API Router auth import docs * Update API Router imports to use `@faustjs/core/api` * Breakout Hooks into individual Pages (#631) * docs: break out hooks * Update links to appropriate hooks url * Logging queries guide * Fix docs site URLs * Fix hooks links Co-authored-by: William Johnston --- docs/next/guides/authentication.mdx | 6 +- docs/next/guides/fetching-data.mdx | 19 +- docs/next/guides/logging-queries.mdx | 65 +++ docs/next/reference/custom-hooks.mdx | 432 ------------------ docs/next/reference/expected-url-params.mdx | 2 +- docs/next/reference/hooks/gqty-hooks.mdx | 25 + docs/next/reference/hooks/hooks.mdx | 15 + docs/next/reference/hooks/useAuth.mdx | 86 ++++ docs/next/reference/hooks/useLogin.mdx | 77 ++++ docs/next/reference/hooks/useLogout.mdx | 42 ++ docs/next/reference/hooks/usePage.mdx | 57 +++ docs/next/reference/hooks/usePost.mdx | 59 +++ docs/next/reference/hooks/usePosts.mdx | 65 +++ docs/next/reference/hooks/usePreview.mdx | 38 ++ docs/tutorial/querying-data.mdx | 37 +- internal/website/sidebars.js | 57 ++- .../components/Features/HomepageFeatures.js | 2 +- packages/next/CHANGELOG.md | 2 +- packages/next/src/gqty/hooks/index.ts | 16 +- 19 files changed, 627 insertions(+), 475 deletions(-) create mode 100644 docs/next/guides/logging-queries.mdx delete mode 100644 docs/next/reference/custom-hooks.mdx create mode 100644 docs/next/reference/hooks/gqty-hooks.mdx create mode 100644 docs/next/reference/hooks/hooks.mdx create mode 100644 docs/next/reference/hooks/useAuth.mdx create mode 100644 docs/next/reference/hooks/useLogin.mdx create mode 100644 docs/next/reference/hooks/useLogout.mdx create mode 100644 docs/next/reference/hooks/usePage.mdx create mode 100644 docs/next/reference/hooks/usePost.mdx create mode 100644 docs/next/reference/hooks/usePosts.mdx create mode 100644 docs/next/reference/hooks/usePreview.mdx diff --git a/docs/next/guides/authentication.mdx b/docs/next/guides/authentication.mdx index 84186d846..071cd2ee4 100644 --- a/docs/next/guides/authentication.mdx +++ b/docs/next/guides/authentication.mdx @@ -44,7 +44,7 @@ Redirect based authentication is the default strategy in Faust.js. This strategy This strategy is great for use cases where your authenticated users are admins/editors/etc. and do not necessarily need a "white label" login/register experience. Typically, you would use the redirect strategy if your primary reason for authentication is previews. -Since Redirect based authentication is the default authentication method, there is no configuration needed on your end to use it. It comes out of the box, and you'll see it in action when using previews or the [`useAuth`](/docs/next/reference/custom-hooks#useauth) hook. +Since Redirect based authentication is the default authentication method, there is no configuration needed on your end to use it. It comes out of the box, and you'll see it in action when using previews or the [`useAuth`](/docs/next/reference/hooks/useAuth) hook. ### Local Based Authentication @@ -149,7 +149,7 @@ The `useLogin` hook exports an object with the following properties: - `data`: the response data from the login request. - `error`: the error from the login request. -For a more detailed explanation of the `useLogin` hook, see the [`useLogin` hook docs](/docs/next/reference/custom-hooks#uselogin) . +For a more detailed explanation of the `useLogin` hook, see the [`useLogin` hook docs](/docs/next/reference/hooks/useLogin) . Upon a successful login, a refresh token will be stored in a secure, http only cookie, as well as the access token in memory to use for subsequent authenticated requests. A login request can be confirmed it succeeded by checking for the `code` property in the `data` object. @@ -241,4 +241,4 @@ export default function Page() { } ``` -**Note:** The [`useAuth`](/docs/next/reference/custom-hooks#useauth) hook fetches the applicable tokens and ensures that the user is authenticated. Therefore, you should check for `isAuthenticated` prior to making authenticated requests, as doing so too early will result in a request without a valid access token. +**Note:** The [`useAuth`](/docs/next/reference/hooks/useAuth) hook fetches the applicable tokens and ensures that the user is authenticated. Therefore, you should check for `isAuthenticated` prior to making authenticated requests, as doing so too early will result in a request without a valid access token. diff --git a/docs/next/guides/fetching-data.mdx b/docs/next/guides/fetching-data.mdx index 3798b436d..92f052140 100644 --- a/docs/next/guides/fetching-data.mdx +++ b/docs/next/guides/fetching-data.mdx @@ -127,11 +127,11 @@ This will ensure Faust.js uses the correct client to make requests on your behal ## Using the Client to Make Queries -Assuming you have created a client using the Faust.js `getClient` function, you will be able to take advantage of many of the added features that Faust.js provides, and also the general features provided by GQty. You can read our [hooks for fething data reference](../reference/custom-hooks) for examples on how to use some of the built-in hooks using the Faust.js client, but the client will support any query to your Headless WordPress API. Let's look at a few examples of how to use the client to make queries. +Assuming you have created a client using the Faust.js `getClient` function, you will be able to take advantage of many of the added features that Faust.js provides, and also the general features provided by GQty. You can read our [hooks for fetching data reference](../reference/hooks) for examples on how to use some of the built-in hooks using the Faust.js client, but the client will support any query to your Headless WordPress API. Let's look at a few examples of how to use the client to make queries. ### The useQuery Hook -If you are not able to use one of the [WordPress-specific hooks](../reference/custom-hooks) you can use the `useQuery` hook to make a query to the Headless WordPress API. This hook is useful for making any query supported by your Headless WordPress API. It essentially exposes your entire generated GQL schema to you for you to use what you need. For example, say you have a `Header` component and you want to fetch menu items from your "Primary" menu in WordPress. You could do so as follows: +If you are not able to use one of the [WordPress-specific hooks](../reference/hooks) you can use the `useQuery` hook to make a query to the Headless WordPress API. This hook is useful for making any query supported by your Headless WordPress API. It essentially exposes your entire generated GQL schema to you for you to use what you need. For example, say you have a `Header` component and you want to fetch menu items from your "Primary" menu in WordPress. You could do so as follows: ```tsx title=src/components/Header.tsx {4,12-15,30-36} import React from 'react'; @@ -222,7 +222,8 @@ export function PostForm() { content: content.value, }, }); - }}> + }} + >