+
+ {query.generalSettings.title}
+{query.generalSettings.description}
+ ) +} +``` + +The following query is automatically generated and requested for you: + +```graphql +query { + generalSettings { + title + description + } +} +``` + +## React Hooks + +GQty has React Hooks for fetching data, mutations, subscriptions, and more: + +- [useQuery](https://gqty.dev/docs/react/fetching-data#usequery) +- [usePaginatedQuery](https://gqty.dev/docs/react/fetching-data#usepaginatedquery) +- [useTransactionQuery](https://gqty.dev/docs/react/fetching-data#usetransactionquery) +- [useLazyQuery](https://gqty.dev/docs/react/fetching-data#uselazyquery) +- [useRefetch](https://gqty.dev/docs/react/fetching-data#userefetch) +- [useMutation](https://gqty.dev/docs/react/mutations#usemutation) +- [useSubscription](https://gqty.dev/docs/react/subscriptions#usesubscription) + +Faust.js exports these hooks from the `client`. You can use them in your React components like so: + +```tsx +import { client } from 'client'; + +export default function App() { + const { + useQuery, + usePaginatedQuery, + useTransactionQuery, + useLazyQuery, + useRefetch, + useMutation, + useSubscription, + } = client; + + return( + ... + ) +} +``` + +## Further Reading + +We recommend reading the ["What Is & Why"](https://gqty.dev/docs/intro) and ["How It Works"](https://gqty.dev/docs/intro/how-it-works) docs to get a better picture of how GQty works. + +Additionally, the following docs may be helpful: + +- [Features](https://gqty.dev/docs/intro/features) +- [Fetching Data in React](https://gqty.dev/docs/react/fetching-data) +- [React Suspense & Usage Without](https://gqty.dev/docs/react/suspense) +- [Helper Functions](https://gqty.dev/docs/client/helper-functions) +- [Troubleshooting](https://gqty.dev/docs/react/troubleshooting) diff --git a/internal/legacy.faustjs.org/versioned_docs/version-development/next/getting-started.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/next/getting-started.mdx new file mode 100644 index 000000000..b23b466e0 --- /dev/null +++ b/internal/legacy.faustjs.org/versioned_docs/version-development/next/getting-started.mdx @@ -0,0 +1,100 @@ +--- +slug: /next/getting-started +title: Getting Started with Next.js +--- + +# Getting Started with Next.js + +## Quick Start + +Please install our Next.js Getting Started example using the following command: + +### On MacOS, Linux, or WSL (bash): + +```bash +npx create-next-app \ + -e https://github.com/wpengine/faustjs/tree/main \ + --example-path examples/next/getting-started \ + --use-npm \ + my-app +cd my-app +``` + +### On Windows with [Powershell Core](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell-core-on-windows?view=powershell-7.1): + +```ps +npx create-next-app ` + -e https://github.com/wpengine/faustjs/tree/main ` + --example-path examples/next/getting-started ` + --use-npm ` + my-app && cd my-app +``` + +> NOTE: If you are on Windows, we suggest using [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). + +Now, copy the sample environment template: + +```bash +cp .env.local.sample .env.local +``` + +Finally, run the dev server: + +```bash +npm run dev +``` + +You can now visit [http://localhost:3000](http://localhost:3000) to see the example site! + ++ +
+ +Currently, the posts and pages you see are coming from our WordPress site at [https://headlessfw.wpengine.com](https://headlessfw.wpengine.com). In the next step, we'll show you how to hook up your own WordPress site. + +## Connecting your WordPress site + +The example app above loads WordPress content from the demo site at [https://headlessfw.wpengine.com](https://headlessfw.wpengine.com). + +To point it to a different WordPress site, first, [make sure you have setup the necessary WordPress plugins.](../tutorial/setup-faustjs#installing-plugins-on-wordpress) + +Once the necessary plugins have been installed, open the `.env.local` file you created earlier, it should look something like this: + +```bash +# Your WordPress site URL +NEXT_PUBLIC_WORDPRESS_URL=https://headlessfw.wpengine.com + +# Plugin secret found in WordPress Settings->Headless +FAUSTWP_SECRET_KEY=YOUR_PLUGIN_SECRET +``` + +Update the `NEXT_PUBLIC_WORDPRESS_URL` value with your WordPress site URL (be sure to include `http://` or `https://`). + +Additionally, update the `FAUSTWP_SECRET_KEY` value with the secret key found in Settings → Headless in your WordPress admin area to support previews. + +
+
+## Setting Your Permalinks
+
+Finally, set your permalinks to the following structure in WP Admin -> Settings -> Permalinks:
+
+```
+/posts/%postname%/
+```
+
+
+
+You can learn more about modifying your permalink structure by viewing the [Permalinks Guide](/docs/next/guides/permalinks).
diff --git a/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/authentication.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/authentication.mdx
new file mode 100644
index 000000000..8c782e107
--- /dev/null
+++ b/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/authentication.mdx
@@ -0,0 +1,248 @@
+---
+slug: /next/guides/auth
+title: Authentication
+description: Use Faust.js' built-in authentication strategies to authenticate users from your WordPress backend
+---
+
+import BaseUrlNotice from '@site/src/mdx/base-url-notice.mdx';
+
+
+
+
+Redirect-based authentication is the default strategy in Faust.js. This strategy involves the user being redirected to WordPress to authenticate. Once the user has shown, the user redirects back to the Next.js application with an authorization code you can then use to request a refresh and access token, thus completing the login process.
+
+This strategy is excellent 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 previewing.
+
+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
+
+
+ 
+
+
+Local Based Authentication is the second strategy available in Faust.js. This strategy involves the user initiating a login request from the Next.js application via the `useLogin` hook. Upon successful login, `useLogin` returns an authorization code used to request a refresh and access token, thus completing the login process.
+
+This strategy is excellent for use cases where you want to support a more "white label" login/register experience. This strategy routes un-authenticated requests to your specified Next.js login page. In addition, users who wish to login/register will not have to interact with WordPress or the WordPress backend at all, giving you the flexibility to implement and fine-tune your user flow.
+
+To use this strategy, you'll need to configure your `faust.config.js` file to use the `local` authentication strategy, in addition to the route of your Next.js login page. Take the following `faust.config.js` file, for example:
+
+```TSX title=faust.config.js {15,16}
+import { config as coreConfig } from '@faustjs/core';
+
+if (!process.env.NEXT_PUBLIC_WORDPRESS_URL) {
+ console.error(
+ 'You must provide a NEXT_PUBLIC_WORDPRESS_URL environment variable, did you forget to load your .env.local file?',
+ );
+}
+
+/**
+ * @type {import("@faustjs/core").Config}
+ */
+export default coreConfig({
+ wpUrl: process.env.NEXT_PUBLIC_WORDPRESS_URL,
+ apiClientSecret: process.env.FAUSTWP_SECRET_KEY,
+ authType: 'local',
+ loginPagePath: '/login',
+});
+```
+
+We define the `authType` to `local` to indicate to the Faust.js config that we use the `local` strategy for authentication. We also describe the `loginPagePath` to `/login` to mark the route of the Next.js login page. This strategy redirects unauthenticated requests to the `/login` route in your Next.js application.
+
+In your `login.tsx` page, you could take advantage of the `useLogin` hook to initiate a login request to the WordPress backend:
+
+```tsx title=pages/login.tsx {9,18}
+import { client } from 'client';
+import { useState } from 'react';
+
+export default function Login() {
+ const { useLogin } = client.auth;
+ const [usernameEmail, setUserNameEmail] = useState('');
+ const [password, setPassword] = useState('');
+
+ const { login, isLoading, data, error } = useLogin();
+
+ const errorMessage = data?.error || error?.message;
+
+ return (
+
+ );
+}
+```
+
+The `useLogin` hook exports an object with the following properties:
+
+- `login`: a function that initiates a request to the WordPress backend for an authorization code that accepts two arguments: `usernameEmail`, which is either the user's username or email as a string, and `password` as a string.
+- `isLoading`: a boolean that indicates whether the login request is in progress.
+- `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/hooks/useLogin) .
+
+Upon successful login, a secure, HTTP only cookie stores a refresh token and the access token in memory for subsequent authenticated requests. You can confirm a login request succeeded by checking for the `code` property in the `data` object.
+
+Additionally, if the login page URL contains a `redirect_uri` query parameter, it will redirect the user to the specified URL upon successful login.
+
+Finally, you can create a `logout.tsx` page to handle logout requests. This is done by using the `useLogout` hook:
+
+```tsx title="src/pages/logout.tsx"
+import { client } from 'client';
+import { useRouter } from 'next/router';
+import { useEffect } from 'react';
+export default function Logout() {
+ const router = useRouter();
+ const { isLoggedOut, logout } = client.auth.useLogout();
+ useEffect(() => {
+ if (isLoggedOut !== undefined) {
+ return;
+ }
+
+ // Initiate the logout process.
+ // This could also be called on a button click, for example, in a nav menu.
+ logout();
+ }, [isLoggedOut, logout]);
+
+ useEffect(() => {
+ if (isLoggedOut) {
+ // The user was successfully logged out. Redirect them.
+ router.push('/');
+ }
+ }, [router, isLoggedOut]);
+ return <>Logging out...;
+}
+```
+
+The `useLogout` hook exports an object with the following properties:
+
+- `logout`: a function that initiates a request to the logout middleware to remove the refresh token from the cookie.
+- `isLoading`: a boolean that indicates whether the logout request is in progress.
+- `isLoggedOut`: a boolean that indicates whether the logout request was successful.
+
+
+
+## Making Authenticated Requests
+
+In the Faust.js client, you can use `useQuery`, `usePost`, `usePage`, etc., to request the WordPress backend.
+
+These are exported from the `client` like so:
+
+```tsx {1,4}
+import { client } from 'client';
+
+export default function Page() {
+ const { useQuery } = client;
+
+ return(
+ ...
+ )
+}
+```
+
+Requests using the above methodology will be un-authenticated.
+
+To make authenticated requests, use the `auth` property exported from the `client`. This property is essentially a replica of the `client`, except every request gets called with an access token:
+
+```TSX {1,4,5}
+import { client } from 'client';
+
+export default function Page() {
+ const { useMutation, usePreview, useAuth } = client.auth;
+ const { isLoading, isAuthenticated } = useAuth();
+
+ if (isLoading) {
+ return Loading...
;
+ }
+
+ if (!isAuthenticated) {
+ return You are not authenticated!
;
+ }
+
+ return Authenticated content
;
+}
+```
+
+**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` before making authenticated requests, as doing so too early will result in a request without a valid access token.
diff --git a/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/custom-post-types.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/custom-post-types.mdx
new file mode 100644
index 000000000..45837d894
--- /dev/null
+++ b/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/custom-post-types.mdx
@@ -0,0 +1,300 @@
+---
+slug: /next/guides/custom-post-types
+title: Interacting with Custom Post Types
+description: Querying data in custom post types is just as easy as querying for posts or pages in Faust.js.
+---
+
+import BaseUrlNotice from '@site/src/mdx/base-url-notice.mdx';
+
+
+
+Let's create a custom post type for team members. Click the "Get Started" button, and fill out the fields to create a new Content Model. Be sure to mark "API Visibility" to "Public" so we can query the data.
+
+
+
+## Create Fields for the Custom Post Type
+
+Now that we've created the custom post type let's add some fields to it. From **WP-Admin -> Content Modeler**, select the Team Members custom post type.
+
+We'll add three fields:
+
+1. A Media field type. The name will be "Profile Pic" and the API identifier "profilePic".
+2. A Text field type. The name will be "Full Name" and the API identifier "fullName". We'll also select "Use this field as the entry title".
+3. A Rich Text field type. The name will be "Bio" and the API identifier "bio".
+
+
+
+## Add Some Team Members
+
+Now that you have created a custom post type and fields, you can start entering data. Navigate to **WP-Admin -> Team Members** to start creating!
+
+For this example, I've created two team members, Jane and John Doe, with bios and profile pics:
+
+
+
+## Clone the Starter Headless Project
+
+Thus far, you have created a WordPress site with the necessary headless plugins and data. Now, we need to create a frontend app to consume this data.
+
+We will use the getting started example project in Next.js, but the same concepts apply in other frontend frameworks.
+
+[Follow the steps in the getting started with Next.js usage guide to create a frontend app](../getting-started.mdx)
+
+Once your frontend app renders, the structure should look something like this:
+
+```
+my-app/
+ src/
+ client/
+ ..
+ pages/
+ ..
+ components/
+ ..
+ scss/
+ ..
+ public/
+ .env.local
+ .env.local.sample
+ .env.test.sample
+ .eslintrc
+ .gitignore
+ gqty.config.js
+ next-env.d.ts
+ package.json
+ README.md
+ tsconfig.json
+```
+
+### Regenerate the GraphQL Schema
+
+Your schema is a TypeScript representation of your WordPress site. Since we have added some custom post types and fields, we'll want to regenerate this schema to ensure it's up to date. To restore your schema from the Next.js getting started example, run:
+
+```bash
+npm run generate
+```
+
+[Learn more about generating your client/schema here.](fetching-data.mdx)
+
+#### Troubleshooting
+
+##### "GraphQL introspection is not allowed"
+
+If you run into the error message `GraphQL introspection is not allowed, but the query contained __schema or __type`, you will have to enable introspection temporarily.
+
+[Introspection is disabled by default in WPGraphQL.](https://www.wpgraphql.com/docs/security/#introspection-disabled-by-default) To enable it, go to WP Admin -> GraphQL -> Enable Public Introspection.
+
+If you are using something other than `WPGraphQL` you will need to refer to the documentation to enable introspection.
+
+Once the schema file generates, you can then disable introspection again.
+
+### Run the Dev Server
+
+Run the following command to start the dev server:
+
+```bash
+npm run dev
+```
+
+You should now be able to access the starter project at [http://localhost:3000](http://localhost:3000)
+
+### Create a Team Page
+
+We'll create a team page in `src/pages/team.tsx` to display the team members:
+
+```tsx title=src/pages/team.tsx
+import Head from 'next/head';
+import { Header, Footer } from 'components';
+import { client } from 'client';
+
+export default function Team() {
+ const { generalSettings } = client.useQuery();
+
+ return (
+ <>
+ 
+
+### Query for Team Members
+
+When querying custom post types in Faust.js, you can leverage the `useQuery` hook exported from the client. `useQuery` allows you to access all of WordPress' data. You'll also notice it's typed from your schema, making things super easy to find.
+
+
+
+Let's get the team members using the `useQuery` hook:
+
+```tsx title=src/pages/team.tsx {6,8}
+import Head from 'next/head';
+import { Header, Footer } from 'components';
+import { client } from 'client';
+
+export default function Team() {
+ const { useQuery } = client;
+ const { generalSettings } = useQuery();
+ const teamMembers = useQuery().teamMembers()?.nodes;
+
+ return (
+ <>
+
+
+ Team Members
+
+ 
+
+ );
+}
+```
+
+Notice we are getting the `TeamMember` TypeScript type from the client and generated schema.
+
+### Put it all Together
+
+Finally, let's hook up the `TeamMember` component to the team page.
+
+```tsx title=src/pages/team.tsx {4,27-29}
+import Head from 'next/head';
+import { Header, Footer } from 'components';
+import { client } from 'client';
+import TeamMember from 'components/teamMember';
+
+export default function Team() {
+ const { useQuery } = client;
+ const { generalSettings } = useQuery();
+
+ const teamMembers = useQuery().teamMembers()?.nodes;
+
+ return (
+ <>
+ {teamMember?.fullName}
+ +
+
+ Team Members
+ + {teamMembers.map((teamMember) => ( +
+
+## Learnings
+
+In this guide, we demonstrated:
+
+- How to create custom post types/fields using [Atlas Content Modeler](https://github.com/wpengine/atlas-content-modeler)
+- Creating data for your custom post types
+- Creating a starter frontend project to consume your WordPress data
+- Using the `useQuery` custom React hook in the framework to query your custom post type data in GraphQL
diff --git a/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/fetching-data.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/fetching-data.mdx
new file mode 100644
index 000000000..b3d6f092a
--- /dev/null
+++ b/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/fetching-data.mdx
@@ -0,0 +1,289 @@
+---
+slug: /next/guides/fetching-data
+title: Fetching data from Headless WordPress with Faust.js
+description: Faust.js makes fetching data from Headless WordPress incredibly easy with GQty.
+---
+
+import BaseUrlNotice from '@site/src/mdx/base-url-notice.mdx';
+
+
+
+
+
+ + + {title} + +
+ {description &&{description}
} +
+
+ -
+ {links?.map((link) => (
+
- + + {link.label} + + + ))} +
+
+Faust.js does not require your permalink structure to be anything specific. Instead, your permalinks should map to the structure of your [Next.js pages](https://nextjs.org/docs/basic-features/pages).
+
+For example, your permalink structure might look like this in WordPress:
+
+```
+/posts/%postname%/
+```
+
+Therefore, your Next.js pages structure should look like this:
+
+```bash {5,6}
+my-app/
+ pages/
+ _app.tsx
+ index.tsx
+ posts/
+ [postSlug].tsx
+ next-env.d.ts
+ package-lock.json
+ package.json
+ README.md
+ tsconfig.json
+```
+
+Notice the `posts` directory and the accompanying `[postSlug].tsx` file. Thus, your permalink structure (`/posts/%postname%/`) map to your Faust.js site posts structure (`/posts/[postSlug]`).
+
+As long as these two structures match, your permalink structure will work.
+
+## Example
+
+Lets say you wanted all of your posts to be under `/blog/`. You would modify your permalink structure to:
+
+```
+/blog/%postname%/
+```
+
+Then, in your Faust.js project, you would create a `/blog/` directory and create a `/blog/[postSlug].tsx` file for each of your posts.
+
+```bash {5,6}
+my-app/
+ pages/
+ _app.tsx
+ index.tsx
+ blog/
+ [postSlug].tsx
+ next-env.d.ts
+ package-lock.json
+ package.json
+ README.md
+ tsconfig.json
+```
diff --git a/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/post-page-previews.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/post-page-previews.mdx
new file mode 100644
index 000000000..56e5cf36a
--- /dev/null
+++ b/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/post-page-previews.mdx
@@ -0,0 +1,164 @@
+---
+slug: /next/guides/post-page-previews
+title: Setting Up Post and Page Previews
+description: View WordPress preview post/page content on your headless frontend with Faust.js
+---
+
+import BaseUrlNotice from '@site/src/mdx/base-url-notice.mdx';
+
+
+
+### Add your Headless Secret to your `.env.local` File
+
+Add the `FAUSTWP_SECRET_KEY` key to your `.env.local` file with the headless secret as the value. Your `.env.local` file should already have a value for `NEXT_PUBLIC_WORDPRESS_URL`. The file should look something like this:
+
+```bash title=.env.local {13}
+# Your WordPress site URL
+NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8080
+
+# Plugin secret found in WordPress Settings->Headless
+FAUSTWP_SECRET_KEY=xxxx
+```
+
+### Ensure you've created your `faust.config.js` file and are importing it in your `_app.tsx`
+
+Like the [`next/getting-started`](https://github.com/wpengine/faustjs/tree/main/examples/next/getting-started) Faust.js example, your [`faust.config.js`](https://github.com/wpengine/faustjs/blob/main/examples/next/getting-started/src/faust.config.js) file will live in the `src` directory.
+
+You'll need to import it at the top of your `_app.tsx` file to ensure the `config` is set, and your Faust.js app initializes appropriately.
+
+```tsx title=src/pages/_app.tsx {1}
+import 'faust.config';
+import { FaustProvider } from '@faustjs/next';
+import { client } from 'client';
+import type { AppProps } from 'next/app';
+
+export default function MyApp({ Component, pageProps }: AppProps) {
+ return (
+ <>
+ loading...
; + } + + if (node === null) { + returnPost not found
; + } + + switch (typeName) { + case 'Page': { + return
+
+Notice the **Publish** button is also visible, meaning that you still need to publish the post. Therefore you can now view the post on the frontend without being authenticated.
+
+Clicking on **Preview in new tab** should take you to your post preview page with the current preview content:
+
+
+
+> **NOTE**: If you are having problems viewing Custom Post Type (CPT) previews using the above example,
+> you need to make sure you have installed the latest version of the WPGraphQL plugin (> v1.6.11).
+> It especially contains a bug fix when the draft previews query returns null for CPTs without revisions.
diff --git a/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/sitemaps.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/sitemaps.mdx
new file mode 100644
index 000000000..8ce2b5909
--- /dev/null
+++ b/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/sitemaps.mdx
@@ -0,0 +1,232 @@
+---
+slug: /next/guides/sitemaps
+title: Sitemaps
+description: Generate sitemaps for your Faust.js site
+---
+
+Sitemaps can be a complicated process when using WordPress in a headless environment. Thankfully, Faust.js takes care of all your sitemap needs through a simple piece of Next.js middleware, [`handleSitemapRequests`](/docs/next/reference/handle-sitemap-requests).
+
+## How It Works
+
+`handleSitemapRequests` works by proxying your existing sitemaps from WordPress to your frontend, while replacing any WordPress URLs with your headless frontend's URL.
+
+This means there is no constraints in how your sitemaps are created on WordPress, giving you the flexibility to use plugins such as [Yoast](https://wordpress.org/plugins/wordpress-seo/) or [XML Sitemaps](https://wordpress.org/plugins/google-sitemap-generator/). As long as your WordPress sitemaps matches the following criteria, they will be proxied:
+
+- Conform to the [XML Sitemaps specification](https://www.sitemaps.org/protocol.html)
+- Has `sitemap` in their pathname (ex. `/page-sitemap.xml`)
+- Has `.xml` as their extension
+
+## Setup
+
+To get started, we'll first have to define a piece of middleware in our Next.js `pages` directory. The file must be named `_middleware.ts`:
+
+```tsx title="src/pages/_middleware.ts"
+import { NextRequest, NextResponse } from 'next/server';
+
+export default async function _middleware(req: NextRequest) {
+ return NextResponse.next();
+}
+```
+
+This is what a default Next.s middleware looks like. Having it at the root of the `pages` directory means that every request to your site will first go through this middleware. You can read more on Next.js middleware [here](https://nextjs.org/docs/middleware).
+
+The middleware above will currently do nothing, as it's an empty function that goes to the "next" middleware via `NextResponse.next()`. Let's add our sitemap handling code:
+
+```tsx title="src/pages/_middleware.ts"
+import { handleSitemapRequests } from '@faustjs/next/middleware';
+import { NextRequest, NextResponse } from 'next/server';
+
+export default async function _middleware(req: NextRequest) {
+ const sitemapRequest = await handleSitemapRequests(req, {
+ wpUrl: process.env.NEXT_PUBLIC_WORDPRESS_URL,
+ sitemapIndexPath: `/wp-sitemap.xml`,
+ });
+
+ if (sitemapRequest) {
+ return sitemapRequest;
+ }
+
+ return NextResponse.next();
+}
+```
+
+`handleSitemapRequests` accepts two required arguments. The first is the `req` object passed from the top level Next.js middleware function, and the second is a configuration object. There are two required properties in the configuration object. The first is `wpUrl`, which is the URL of your WordPress site. The second is `sitemapIndexPath`, which is the relative path to the sitemap index file that exists on your WordPress site.
+
+This is all the configuration you need to get started. As you can see, if you now go to `/wp-sitemap.xml` on your headless frontend, you will see the sitemap index file being proxied over with properly formatted URLs.
+
+## Additional Configuration
+
+### Ignoring Paths
+
+There will be instances in which you don't want to proxy over a specific path. For example, if you have a custom post type that you want to exclude from your sitemap, you can do so by adding it to the `sitemapPathsToIgnore` array.
+
+```tsx title="src/pages/_middleware.ts" {8}
+import { handleSitemapRequests } from '@faustjs/next/middleware';
+import { NextRequest, NextResponse } from 'next/server';
+
+export default async function _middleware(req: NextRequest) {
+ const sitemapRequest = await handleSitemapRequests(req, {
+ wpUrl: process.env.NEXT_PUBLIC_WORDPRESS_URL,
+ sitemapIndexPath: `/wp-sitemap.xml`,
+ sitemapPathsToIgnore: ['/wp-sitemap-users-1.xml'],
+ });
+
+ if (sitemapRequest) {
+ return sitemapRequest;
+ }
+
+ return NextResponse.next();
+}
+```
+
+You can additionally use a wildcard to ignore sitemap paths that may be paginated:
+
+```tsx title="src/pages/_middleware.ts" {8}
+import { handleSitemapRequests } from '@faustjs/next/middleware';
+import { NextRequest, NextResponse } from 'next/server';
+
+export default async function _middleware(req: NextRequest) {
+ const sitemapRequest = await handleSitemapRequests(req, {
+ wpUrl: process.env.NEXT_PUBLIC_WORDPRESS_URL,
+ sitemapIndexPath: `/wp-sitemap.xml`,
+ sitemapPathsToIgnore: ['/wp-sitemap-users-*'],
+ });
+
+ if (sitemapRequest) {
+ return sitemapRequest;
+ }
+
+ return NextResponse.next();
+}
+```
+
+### Defining Next.js Pages for Sitemaps
+
+The above code examples account for adding your WordPress content to your sitemap, but what about the file based pages you've created in Next.js? Say for an example we have `src/pages/about.tsx` and we'd like to include it in our sitemap. That can be done by creating a `pages` property in the `handleSitemapRequests` config object:
+
+```tsx title="src/pages/_middleware.ts" {8-12}
+import { handleSitemapRequests } from '@faustjs/next/middleware';
+import { NextRequest, NextResponse } from 'next/server';
+
+export default async function _middleware(req: NextRequest) {
+ const sitemapRequest = await handleSitemapRequests(req, {
+ wpUrl: process.env.NEXT_PUBLIC_WORDPRESS_URL,
+ sitemapIndexPath: `/wp-sitemap.xml`,
+ pages: [
+ {
+ path: '/about',
+ },
+ ],
+ });
+
+ if (sitemapRequest) {
+ return sitemapRequest;
+ }
+
+ return NextResponse.next();
+}
+```
+
+The `path` property is a relative path to the page you want to include in your sitemap and is the only required field. Take a look at the [reference doc](/docs/next/reference/handle-sitemap-requests#pages) for more of the available options.
+
+### Creating a `/robots.txt` Route
+
+There will most likely be instances where you will need to create a `/robots.txt` route. This is a file that tells search engines what to do with your site. We have a handy function that you can define in your `handleSitemapRequests` config object that has an argument of `sitemapUrl` to be used:
+
+```tsx title="src/pages/_middleware.ts" {8-15}
+import { handleSitemapRequests } from '@faustjs/next/middleware';
+import { NextRequest, NextResponse } from 'next/server';
+
+export default async function _middleware(req: NextRequest) {
+ const sitemapRequest = await handleSitemapRequests(req, {
+ wpUrl: process.env.NEXT_PUBLIC_WORDPRESS_URL,
+ sitemapIndexPath: `/wp-sitemap.xml`,
+ async robotsTxt(sitemapUrl) {
+ return `
+ User-agent: *
+ Allow: /
+
+ Sitemap: ${sitemapUrl}
+ `;
+ },
+ });
+
+ if (sitemapRequest) {
+ return sitemapRequest;
+ }
+
+ return NextResponse.next();
+}
+```
+
+## Examples
+
+Below you can find some drop in examples for different XML Sitemap configurations on WordPress.
+
+:::note
+
+Be sure to define your `pages` property in your `handleSitemapRequests` config object if you have any Next.js specific pages you want included in your sitemap.
+
+:::
+
+### Usage with default WordPress Sitemaps
+
+Below is a drop in configuration using default WordPress sitemaps. This assumes you want to ignore the "users" sitemap:
+
+```tsx title="src/pages/_middleware.ts"
+import { handleSitemapRequests } from '@faustjs/next/middleware';
+import { NextRequest, NextResponse } from 'next/server';
+
+export default async function _middleware(req: NextRequest) {
+ const sitemapRequest = await handleSitemapRequests(req, {
+ wpUrl: process.env.NEXT_PUBLIC_WORDPRESS_URL,
+ sitemapIndexPath: `/wp-sitemap.xml`,
+ sitemapPathsToIgnore: ['/wp-sitemap-users-*'],
+ async robotsTxt(sitemapUrl) {
+ return `
+ User-agent: *
+ Allow: /
+
+ Sitemap: ${sitemapUrl}
+ `;
+ },
+ });
+
+ if (sitemapRequest) {
+ return sitemapRequest;
+ }
+
+ return NextResponse.next();
+}
+```
+
+### Usage with Yoast
+
+Below is a drop in configuration using Yoast's sitemap. This assumes you want to ignore the "author" sitemap:
+
+```tsx title="src/pages/_middleware.ts"
+import { handleSitemapRequests } from '@faustjs/next/middleware';
+import { NextRequest, NextResponse } from 'next/server';
+
+export default async function _middleware(req: NextRequest) {
+ const sitemapRequest = await handleSitemapRequests(req, {
+ wpUrl: process.env.NEXT_PUBLIC_WORDPRESS_URL,
+ sitemapIndexPath: `/sitemap_index.xml`,
+ sitemapPathsToIgnore: ['/author-sitemap.xml'],
+ async robotsTxt(sitemapUrl) {
+ return `
+ User-agent: *
+ Allow: /
+
+ Sitemap: ${sitemapUrl}
+ `;
+ },
+ });
+
+ if (sitemapRequest) {
+ return sitemapRequest;
+ }
+
+ return NextResponse.next();
+}
+```
diff --git a/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/ssr-ssg.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/ssr-ssg.mdx
new file mode 100644
index 000000000..b0cb1c084
--- /dev/null
+++ b/internal/legacy.faustjs.org/versioned_docs/version-development/next/guides/ssr-ssg.mdx
@@ -0,0 +1,257 @@
+---
+slug: /next/guides/ssr-ssg
+title: Server-side Rendering & Static Generation
+description: Use Faust.js and Next.js to statically generate your Headless WordPress site
+---
+
+import BaseUrlNotice from '@site/src/mdx/base-url-notice.mdx';
+
+Recent Posts
+ {usePosts()?.nodes.map((post) => ( +Recent Posts
+ {usePosts()?.nodes.map((post) => ( +{title}
+ {usePosts()?.nodes.map((post) => ( +
+
+
+
+ + + {title} + +
+ {description &&{description}
} +
+
+ -
+ {links?.map((link) => (
+
- + + {link.label} + + + ))} +
- + + + GitHub + + + +
{post?.title()}
+ +
+
+ ))}
+
+ );
+}
+```
+
+Notice the above file is `index.tsx`, but `[categorySlug]` is used in the URL. So the `usePosts()` hook will make a request using the `categorySlug` param to get posts for the category based on the value stored in `categorySlug`.
diff --git a/internal/legacy.faustjs.org/versioned_docs/version-development/next/reference/faust-provider.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/next/reference/faust-provider.mdx
new file mode 100644
index 000000000..e2bf4fc82
--- /dev/null
+++ b/internal/legacy.faustjs.org/versioned_docs/version-development/next/reference/faust-provider.mdx
@@ -0,0 +1,71 @@
+---
+slug: /next/reference/faust-provider
+title: Using FaustProvider
+description: The FaustProvider React component wraps your app to provide context to Faust.js
+---
+
+import BaseUrlNotice from '@site/src/mdx/base-url-notice.mdx';
+
+
+
+
+ {post.title()}
+
+
+
+
+ Loading...
;
+ }
+
+ return Authenticated content
;
+}
+```
+
+Additionally, the example below shows how to use `useAuth` with the `shouldRedirect` option set to `false`. This will disable the automatic redirect to the appropriate URL to authenticate, and allows you to control how the page's content is rendered in an unauthenticated state:
+
+```tsx title=src/pages/gated-content.tsx {5-7,13-15}
+import { client } from 'client';
+
+export default function Gated() {
+ const { useAuth } = client.auth;
+ const { isLoading, isAuthenticated, authResult } = useAuth({
+ shouldRedirect: false,
+ });
+
+ if (isLoading) {
+ return Loading...
;
+ }
+
+ if (!isAuthenticated) {
+ return You are not authenticated! Please login.
;
+ }
+
+ return Authenticated content
;
+}
+```
+
+`useAuth` exports an object with the following properties:
+
+- `isLoading`: A boolean that indicates whether the `useAuth` function is currently checking if a user is authenticated.
+- `isAuthenticated`: A boolean that indicates whether the user is authenticated.
+- `authResult`: The result from checking if there is an authenticated user.
+
+ If there is an authenticated user, the `authResult` will be `true`. Otherwise, the `authResult` will be an object with the following properties:
+
+ ```js title="The authResult object when there is no authenticated user"
+ {
+ /**
+ * An absolute URL to the WordPress backend that the user should be redirected to in order to authenticate.
+ * This property is used for the "redirect" based authentication strategy
+ */
+ redirect: 'xxxx';
+
+ /*
+ * A relative URL path to the local login page as specified in the `loginPagePath` option.
+ * This property is used for the "local" based authentication strategy
+ */
+ login: 'xxxx';
+ }
+ ```
+
+ The `authResult` can be helpful if you want to handle the redirection yourself, instead of the `useAuth` hook.
diff --git a/internal/legacy.faustjs.org/versioned_docs/version-development/next/reference/hooks/useLogin.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/next/reference/hooks/useLogin.mdx
new file mode 100644
index 000000000..0a8e69655
--- /dev/null
+++ b/internal/legacy.faustjs.org/versioned_docs/version-development/next/reference/hooks/useLogin.mdx
@@ -0,0 +1,81 @@
+---
+slug: /next/reference/hooks/useLogin
+title: useLogin
+description: The useLogin hook provides a way to log in a user
+---
+
+import BaseUrlNotice from '@site/src/mdx/base-url-notice.mdx';
+
+{page?.title()}
+ +{page?.title()}
+ +{post?.title()}
+ +{post?.title()}
+ +Recent Posts
+-
+ {posts?.nodes.map((post) => (
+
- {post.title()} + ))} +
Recent Posts
+-
+ {posts?.nodes.map((post) => (
+
- {post.title()} + ))} +
loading...
; + } + + if (result.type === 'page') { + if (!result.page) { + return <>Not Found; + } + + returnloading...
; + } + + if (node === null) { + returnPost not found
; + } + + switch (typeName) { + case 'Page': { + returnloading...
; + } + + if (node === null) { + returnPost not found
; + } + + switch (typeName) { + case 'Page': { + return{event.title()}
+{event.content()}
+ + ); + } + // Add additional custom post types here as needed + default: { + throw new Error(`Unspecified post type preview: ${typeName}`); + } + } +} +``` diff --git a/internal/legacy.faustjs.org/versioned_docs/version-development/next/reference/is404.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/next/reference/is404.mdx new file mode 100644 index 000000000..9f487de49 --- /dev/null +++ b/internal/legacy.faustjs.org/versioned_docs/version-development/next/reference/is404.mdx @@ -0,0 +1,29 @@ +--- +slug: /next/reference/is404 +title: is404() +description: The is404() function helps you determine when Next.js should return a 404 response. +--- + +## Description + +Determines when a dynamic post, page, or category route is requested for which no corresponding WordPress post, page, or category exists. + +See [Expected URL Params](./expected-url-params) for more on how dynamic routes are mapped to a specific page, post, or category in WordPress. + +:::note +This function is only useful on routes that include one of the [expected URL params](./expected-url-params). +If none of the expected URL params are present in the provided context, `is404()` will always return `true`. +::: + +## Parameters + +- `Context`: Either the `GetStaticPropsContext` or the `GetServerSidePropsContext` from Next.js, depending on which function you are resolving props from. +- `Is404Config`: An object with a `client` property containing [your GQty client](../guides/fetching-data#setting-up-your-client). + +## Return + +Returns `true` when the requested WordPress post, page, or category does not exist. + +## Usage + +View the guide on [Handling 404s with is404](../guides/handle-404s) for a detailed description and example code. diff --git a/internal/legacy.faustjs.org/versioned_docs/version-development/next/reference/with-faust.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/next/reference/with-faust.mdx new file mode 100644 index 000000000..277343081 --- /dev/null +++ b/internal/legacy.faustjs.org/versioned_docs/version-development/next/reference/with-faust.mdx @@ -0,0 +1,77 @@ +--- +slug: /next/reference/with-faust +title: Using withFaust +description: withFaust is a helper function that merges your next.config.js with Faust related configuration. +--- + +The `withFaust` helper function is used to merge your `next.config.js` config with necessary Faust.js configuration. + +## Usage + +To use `withFaust`, create a `next.config.js` file in your project root with the following content: + +```js title="next.config.js" +const { withFaust } = require('@faustjs/next'); + +/** + * @type {import('next').NextConfig} + **/ +module.exports = withFaust(); +``` + +If you already have a `next.config.js` file, you can use the first argument of `withFaust` to merge in your existing config. + +Take the following example, where we have a custom `next.config.js` handling a rewrite: + +```js title="next.config.js" +const { withFaust } = require('@faustjs/next'); + +const nextConfig = { + async rewrites() { + return [ + { + source: '/about', + destination: '/', + }, + ]; + }, +}; + +/** + * @type {import('next').NextConfig} + **/ +module.exports = withFaust(nextConfig); +``` + +## Additional Options + +`withFaust` also accepts a second argument for `withFaustConfig`. `withFaustConfig` represented as a TypeScript interface looks like: + +```ts +interface WithFaustConfig { + // Where preview links will be redirected to. + previewDestination?: string; +} +``` + +For example, if you wanted to change the default preview destination from `/preview` to `/previews`, you can do so by passing the following to `withFaust`: + +```js title="next.config.js" +const { withFaust } = require('@faustjs/next'); + +const nextConfig = {}; + +const withFaustConfig = { + previewDestination: '/previews', +}; + +/** + * @type {import('next').NextConfig} + **/ +module.exports = withFaust(nextConfig, withFaustConfig); +``` + +:::note +If you change the `previewDestination` path, do not forget to create an associated `page` with the same name for that destination. +Otherwise the framework will redirect to a non existing page and it will show a `404` response. +::: diff --git a/internal/legacy.faustjs.org/versioned_docs/version-development/release-notes.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/release-notes.mdx new file mode 100644 index 000000000..1d6b423af --- /dev/null +++ b/internal/legacy.faustjs.org/versioned_docs/version-development/release-notes.mdx @@ -0,0 +1,224 @@ +--- +slug: release-notes +title: Faust.js 0.9.0 - 0.12.0 +description: The former location of Faust.js release notes +--- + +## Changelogs + +For package versions greater than 0.12.0, visit the individual changelog pages: + +- [@faustjs/core](./changelog/core) +- [@faustjs/next](./changelog/next) +- [@faustjs/react](./changelog/react) + +## Release Notes + +### Faust.js 0.12.0 - Oct 5, 2021 + +For a full list of features/changes, visit the releases on GitHub: + +- [@faustjs/core@0.12.0](https://github.com/wpengine/faustjs/releases/tag/%40faustjs%2Fcore%400.12.0) +- [@faustjs/next@0.12.0](https://github.com/wpengine/faustjs/releases/tag/%40faustjs%2Fnext%400.12.0) +- [@faustjs/react@0.12.0](https://github.com/wpengine/faustjs/releases/tag/%40faustjs%2Freact%400.12.0) + +#### Breaking Changes + +First, you will need to create a new file at your [Next.js pages directory](https://nextjs.org/docs/basic-features/pages), `src/pages/api/faust/[[...route]].ts` with the following content: + +```ts title="src/pages/api/faust/[[...route]].ts" +import 'faust.config'; +import { apiRouter } from '@faustjs/core/api'; + +export default apiRouter; +``` + +Then, you will want to delete the `src/pages/api/auth/wpe-headless.ts` file if it exists. + +Finally, replace your current `src/faust.config.js` file with the following: + +```js title="src/faust.config.js" {1,12} +import { config as coreConfig } from '@faustjs/core'; + +if (!process.env.NEXT_PUBLIC_WORDPRESS_URL) { + console.error( + 'You must provide a NEXT_PUBLIC_WORDPRESS_URL environment variable, did you forget to load your .env.local file?', + ); +} + +/** + * @type {import("@faustjs/core").Config} + */ +export default coreConfig({ + wpUrl: process.env.NEXT_PUBLIC_WORDPRESS_URL, + apiClientSecret: process.env.WP_HEADLESS_SECRET, +}); +``` + +**Notice**: `headlessConfig` has been renamed to just `config` + +[Take a look at the Getting Started example for a closer look at these breaking changes.](https://github.com/wpengine/faustjs/tree/main/examples/next/getting-started) + +### Faust.js 0.11.0 - Sept 23, 2021 + +#### Features + +- `GQty` has been updated to `2.0.1` to bring support to [`Unions` and `Interfaces` with the `$on` property](https://github.com/gqty-dev/gqty/releases). ([#491](https://github.com/wpengine/faustjs/pull/491)) + +#### Breaking Changes + +Please update the `@gqty/cli` package in your `package.json` to `2.0.1` and run `npm run generate`. + +### Faust.js 0.10.2 - Sept 13, 2021 + +#### Fixes + +- Fixed the `WithRevisions` interface to use proper `Maybe<>` type checks ([#452](https://github.com/wpengine/faustjs/pull/452/files)) + +### Faust.js 0.10.1 - Sept 10, 2021 + +#### Fixes + +- Fixed an issue where the `ObjectTypeNames` client interface was incompatible with `@faustjs/core` ([#445](https://github.com/wpengine/faustjs/pull/445)) + +#### Chore & Maintenance + +- Updated `@faustjs` package dependencies to their latest versions ([#440](https://github.com/wpengine/faustjs/pull/440)) + +### Faust.js 0.10.0 - Sept 08, 2021 + +Release `0.10.0` of the NPM packages include **BREAKING CHANGES**. Existing users of Faust.js will need to make the following changes: + +#### Step 1 - Update the WPE Headless Plugin + +Ensure that you are on version `0.6.0` or later of the WPE Headless Plugin. + +#### Step 2 - Update `preview.tsx` file + +If you started from the `next/getting-started` example, replace the contents of `src/pages/preview.tsx` with the following: + +```tsx +import { PageComponent } from './[...pageUri]'; +import { PostComponent } from './posts/[postSlug]'; +import { client } from 'client'; + +export default function Preview() { + const { usePreview } = client.auth; + const result = usePreview(); + + if (client.useIsLoading() || !result) { + returnloading...
; + } + + if (result.type === 'page') { + if (!result.page) { + return <>Not Found; + } + + return+ + Discord + - Interactive chat support on Discord. + +--- + +Premium Users get the above plus chat support, a Solutions Architect, and a Technical Account Manager. diff --git a/internal/faustjs.org/docs/tutorial/basic-headless-site.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/tutorial/basic-headless-site.mdx similarity index 100% rename from internal/faustjs.org/docs/tutorial/basic-headless-site.mdx rename to internal/legacy.faustjs.org/versioned_docs/version-development/tutorial/basic-headless-site.mdx diff --git a/internal/faustjs.org/docs/tutorial/dev-env-setup.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/tutorial/dev-env-setup.mdx similarity index 100% rename from internal/faustjs.org/docs/tutorial/dev-env-setup.mdx rename to internal/legacy.faustjs.org/versioned_docs/version-development/tutorial/dev-env-setup.mdx diff --git a/internal/faustjs.org/docs/tutorial/first-react-component.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/tutorial/first-react-component.mdx similarity index 100% rename from internal/faustjs.org/docs/tutorial/first-react-component.mdx rename to internal/legacy.faustjs.org/versioned_docs/version-development/tutorial/first-react-component.mdx diff --git a/internal/faustjs.org/docs/tutorial/nextjs-intro.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/tutorial/nextjs-intro.mdx similarity index 100% rename from internal/faustjs.org/docs/tutorial/nextjs-intro.mdx rename to internal/legacy.faustjs.org/versioned_docs/version-development/tutorial/nextjs-intro.mdx diff --git a/internal/faustjs.org/docs/tutorial/querying-data.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/tutorial/querying-data.mdx similarity index 100% rename from internal/faustjs.org/docs/tutorial/querying-data.mdx rename to internal/legacy.faustjs.org/versioned_docs/version-development/tutorial/querying-data.mdx diff --git a/internal/faustjs.org/docs/tutorial/setup-faustjs.mdx b/internal/legacy.faustjs.org/versioned_docs/version-development/tutorial/setup-faustjs.mdx similarity index 98% rename from internal/faustjs.org/docs/tutorial/setup-faustjs.mdx rename to internal/legacy.faustjs.org/versioned_docs/version-development/tutorial/setup-faustjs.mdx index 82053641e..f5201d94d 100644 --- a/internal/faustjs.org/docs/tutorial/setup-faustjs.mdx +++ b/internal/legacy.faustjs.org/versioned_docs/version-development/tutorial/setup-faustjs.mdx @@ -89,11 +89,11 @@ You'll also need a `.env.local` file to hold your environment variables: # Your WordPress site URL NEXT_PUBLIC_WORDPRESS_URL=http://your-wordpress-site.com -# Plugin secret found in WordPress Settings->Faust +# Plugin secret found in WordPress Settings->Headless FAUSTWP_SECRET_KEY=YOUR_PLUGIN_SECRET ``` -Replace the `NEXT_PUBLIC_WORDPRESS_URL` value with the URL of your WordPress site. Additionally, grab the Headless Secret from WordPress Settings -> Faust and replace it with the `FAUSTWP_SECRET_KEY` value. +Replace the `NEXT_PUBLIC_WORDPRESS_URL` value with the URL of your WordPress site. Additionally, grab the Headless Secret from WordPress Settings -> Headless and replace it with the `FAUSTWP_SECRET_KEY` value.