feat: Point getting-started to a live demo URL for a faster new user …

…experience (BH-895) (#155)

* feat: Use a demo WORDPRESS_URL by default

Makes a missing WORDPRESS_URL or .env.local a
warning instead of an exception.

Shows content from a live demo site instead of
failing to build.

* feat: Warn if WP_HEADLESS_SECRET is not set

Instead of throwing an exception and failing to
continue, warn the user if WP_HEADLESS_SECRET is
unset.

That way they can continue without env vars and
still see demo content. (Previews will not work
until they act on the warning.)

* feat: Add a posts link to the hard-coded menu

Swap out for a dynamic menu in another PR.

* docs: Redo quick start docs

To create the frontend app first, then repoint
to a WordPress instance.

* docs: Redo getting started docs

To create the frontend app first, then repoint
to a WordPress instance.

* docs: frontend to front-end for consistency

* docs: Prompt to set the front-end site URL

README.md

@@ -10,16 +10,32 @@ _🚧 **Note:** This project is in the early stages of development_
 
 Eager to try out the Headless Framework? Here's how you can get started:
 
-1. Create a WordPress site if you haven't already. We recommend using [Local](https://localwp.com/)!
-1. Download, upload, and activate the `wpe-headless` plugin. [(Plugin Download)](https://wp-product-info.wpesvc.net/v1/plugins/wpe-headless?download)
-1. Install [WPGraphQL](https://wordpress.org/plugins/wp-graphql/) on the WordPress site if it's not already installed.
-   - WPGraphQL can be installed directly from Settings → Headless as well!
+### Create a front-end app
+
 1. Create a new Next.js app from our [getting-started project](https://github.com/wpengine/headless-framework/tree/canary/examples/getting-started): `npx create-next-app -e https://github.com/wpengine/headless-framework/tree/canary --example-path examples/getting-started --use-npm`
-1. `cp .env.local.sample .env.local`
-1. Populate `WORDPRESS_URL` in `.env.local` with the full URL to your WordPress site, including the `http://` or `https://` prefix.
-1. Populate `WP_HEADLESS_SECRET` in `.env.local` with the secret key found at Settings → Headless in your WordPress admin area.
-1. In WordPress Settings → Headless, populate the "Front-end site URL" with `http://localhost:3000`
-1. `cd my-app && npm run dev`
+2. `cd my-app && npm run dev`
+3. See your site at http://localhost:3000.
+
+### Point the app to your own WordPress site
+
+The sample app loads WordPress content from our demo site at https://headlessfw.wpengine.com.
+
+Point it to your own WordPress site instead:
+
+1. Create a WordPress site if you haven't already. We recommend [Local](https://localwp.com/) to try things out locally, or you can use a live WordPress site.
+2. Download, upload, and activate the `wpe-headless` plugin. [(Plugin Download)](https://wp-product-info.wpesvc.net/v1/plugins/wpe-headless?download)
+3. Install [WP GraphQL](https://wordpress.org/plugins/wp-graphql/) on the WordPress site if it's not already installed.
+
+Then, in your front-end app directory:
+
+4. `cp .env.local.sample .env.local` to create a file that will contain your environment variables.
+5. Populate `WORDPRESS_URL` in `.env.local` with the full URL to your WordPress site, including the `http://` or `https://` prefix.
+6. Populate `WP_HEADLESS_SECRET` in `.env.local` with the secret key found at Settings → Headless in your WordPress admin area.
+7. `npm run dev` (kill and restart npm if it was already running)
+
+You'll see the same site with your WordPress posts instead of ours.
+
+To enable post previews, set your front-end app URL on the WordPress Settings → Headless page (for example, `http://localhost:3000` when testing locally).
 
 ➡️ [Learn more about getting started](/docs/getting-started/)
 

docs/getting-started/README.md

@@ -2,45 +2,55 @@
 
 This guide will get you up and running with our Headless Framework and help you understand what it offers.
 
-## Set up the WordPress plugin
+You should have [Node.js](https://nodejs.org/en/download/) installed first.
 
-Install our [Headless WordPress plugin](https://github.com/wpengine/headless-framework#wordpress-plugin) to get the full benefits of the framework. We recommend [Local](https://localwp.com/) to quickly spin up a local WordPress site. Once you have a WordPress site up and running, [download the plugin](https://wp-product-info.wpesvc.net/v1/plugins/wpe-headless?download) and upload and activate it [through the WordPress Admin](https://wordpress.org/support/article/managing-plugins/#manual-upload-via-wordpress-admin).
+## Create a Next.js app
 
-After activation, you will be redirected to the Headless settings page. The plugin has a dependency on WPGraphQL, so you’ll see a button on the right under the “Get Started with Headless” box to install and activate the WPGraphQL plugin if it’s not already active.
+Our headless framework is built on top of [Next.js](https://nextjs.org/). You get all the amazing features that Next.js provides, plus an easy way to use it with WordPress!
 
-At this point, if you know what the URL to your front-end site is (or is going to be), you can enter that now in the Front-end Site URL field. That’s all you need to do for now on the WordPress side!
+For this guide, we’ll start with an [example project](https://github.com/wpengine/headless-framework/tree/canary/examples/getting-started) to quickly see the power of our framework. To pull it down, use npx (whcih comes with Node.js) with the URL to our example project:
 
-### What is the WordPress plugin doing?
+```npx create-next-app -e https://github.com/wpengine/headless-framework/tree/canary --example-path examples/preview --use-npm```
 
-The plugin ensures that your WordPress site runs smoothly as a headless CMS. From smart content redirects to enabling post previewing to ensuring the right data is available in WPGraphQL, installing the plugin gives you the things you need to run WordPress as a headless CMS. Find a [full list of plugin features here](https://github.com/wpengine/headless-framework#plugin-features).
+create-next-app will prompt you to provide a name for your project. Once you do that and the dependencies are installed, cd into the new project:
 
-## Create a Next.js app
+```cd your-app-name```
 
-Our headless framework is built on top of [Next.js](https://nextjs.org/). You get all the amazing features that Next.js provides, plus an easy way to use it with WordPress!
+Then `npm run dev` and visit your site at http://localhost:3000.
 
-For this guide, we’ll start with an [example project](https://github.com/wpengine/headless-framework/tree/canary/examples/preview) to quickly see the power of our framework. To pull it down, we recommend using npx and create-react-app with the URL to our example project:
+```cp .env.local.sample .env.local```
 
-```npx create-next-app -e https://github.com/wpengine/headless-framework/tree/canary --example-path examples/preview --use-npm```
+## Connect the app to your WordPress site
 
-create-next-app will prompt you to provide a name for your project. Once you do that and the dependencies are installed, cd into the new project and make a copy of .env.local.sample.
+The sample app loads WordPress content from our demo site at https://headlessfw.wpengine.com.
 
-```cp .env.local.sample .env.local```
+Point it to your own WordPress site instead:
+
+1. Create a WordPress site if you haven't already. We recommend [Local](https://localwp.com/) to try things out locally, or you can use a live WordPress site.
+2. Download, upload, and activate the `wpe-headless` plugin. [(Plugin Download)](https://wp-product-info.wpesvc.net/v1/plugins/wpe-headless?download)
+3. Install [WP GraphQL](https://wordpress.org/plugins/wp-graphql/) on the WordPress site if it's not already installed.
+
+Then, in your front-end app directory:
+
+4. `cp .env.local.sample .env.local` to create a file that will contain your environment variables.
+5. Populate `WORDPRESS_URL` in `.env.local` with the full URL to your WordPress site, including the `http://` or `https://` prefix.
+6. Populate `WP_HEADLESS_SECRET` in `.env.local` with the secret key found at Settings → Headless in your WordPress admin area.
+6. `npm run dev` (kill and restart npm if it was already running)
+
+Open or refresh http://localhost:3000 and you should see a list of posts from your WordPress site at the bottom of the front page, and be able to view a single post.
+
+## Set up the WordPress plugin
 
-This config file is where you’ll set the WordPress URL and secret key that ties it all together.
+Install our [Headless WordPress plugin](https://github.com/wpengine/headless-framework#wordpress-plugin) to get the full benefits of the framework. We recommend [Local](https://localwp.com/) to quickly spin up a local WordPress site. Once you have a WordPress site up and running, [download the plugin](https://wp-product-info.wpesvc.net/v1/plugins/wpe-headless?download) and upload and activate it [through the WordPress Admin](https://wordpress.org/support/article/managing-plugins/#manual-upload-via-wordpress-admin).
 
-```
-# Base URL for WordPress
-WORDPRESS_URL=http://yourwpsite.com
+After activation, you will be redirected to the Headless settings page. The plugin has a dependency on WPGraphQL, so you’ll see a button on the right under the “Get Started with Headless” box to install and activate the WPGraphQL plugin if it’s not already active.
 
-# Plugin secret found in WordPress Settings->Headless
-WP_HEADLESS_SECRET=YOUR_PLUGIN_SECRET
-```
+At this point, if you know what the URL to your front-end site is (or is going to be), you can enter that now in the Front-end Site URL field. That’s all you need to do for now on the WordPress side!
 
-Now you’re ready to run the app!
+### What is the WordPress plugin doing?
 
-```npm run dev```
+The plugin ensures that your WordPress site runs smoothly as a headless CMS. From smart content redirects to enabling post previewing to ensuring the right data is available in WPGraphQL, installing the plugin gives you the things you need to run WordPress as a headless CMS. Find a [full list of plugin features here](https://github.com/wpengine/headless-framework#plugin-features).
 
-Open up http://localhost:3000 and you should see a list of posts from your WordPress site and be able to view a single post.
 
 ## Breaking down the example project
 

examples/getting-started/.env.local.sample

@@ -6,8 +6,8 @@
 # Setting NEXT_PUBLIC_WORDPRESS_URL instead of WORDPRESS_URL will allow requests to come from the client-side which may
 # reduce site performance and put extra load on the WordPress backend.
 
-WORDPRESS_URL=http://yourwpsite.com
-# NEXT_PUBLIC_WORDPRESS_URL=http://yourwpsite.com
+WORDPRESS_URL=https://headlessfw.wpengine.com
+# NEXT_PUBLIC_WORDPRESS_URL=https://headlessfw.wpengine.com
 
 # Plugin secret found in WordPress Settings->Headless
 WP_HEADLESS_SECRET=YOUR_PLUGIN_SECRET

examples/getting-started/components/Header.tsx

@@ -16,7 +16,8 @@ function Header({
   // TODO: accept a `menuItems` prop to receive menu items from WordPress.
   const menuItems = [
     { title: 'Home', href: '/' },
-    { title: 'About', href: '/about/' },
+    { title: 'About', href: '/about' },
+    { title: 'Posts', href: '/category/uncategorized' },
     {
       title: 'GitHub',
       href: 'https://github.com/wpengine/headless-framework',

packages/headless/src/api/apolloClient.ts

@@ -15,14 +15,16 @@ import { CookieOptions, getAccessToken } from '../auth';
 
 export type PersistentContext = Record<string, unknown>;
 
-const WP_URL = trimTrailingSlash(
+let WP_URL = trimTrailingSlash(
   process.env.NEXT_PUBLIC_WORDPRESS_URL || process.env.WORDPRESS_URL,
 );
 
 if (!WP_URL) {
+  WP_URL = 'https://headlessfw.wpengine.com';
+
   if (isServerSide()) {
-    throw new Error(
-      'WORDPRESS_URL and NEXT_PUBLIC_WORDPRESS_URL environment variables are not set. Please set WORDPRESS_URL (or NEXT_PUBLIC_WORDPRESS_URL if you wish to also use client-side requests) to your WPGraphQL endpoint.',
+    console.warn(
+      'DEMO MODE: The WORDPRESS_URL environment variable is not set. Using demo site URL of https://headlessfw.wpengine.com. Set WORDPRESS_URL to your WordPress site URL and install the WPGraphQL plugin to see your own content.',
     );
   }
 }

packages/headless/src/auth/authorize.ts

@@ -18,8 +18,8 @@ const AUTH_URL = trimTrailingSlash(
 const API_CLIENT_SECRET = process.env.WP_HEADLESS_SECRET;
 
 if (!API_CLIENT_SECRET && isServerSide()) {
-  throw new Error(
-    'WP_HEADLESS_SECRET environment variable is not set. Please set it to your WPGraphQL endpoint if you wish to use authenticated API calls.',
+  console.warn(
+    'The WP_HEADLESS_SECRET environment variable is not set. Install the WP Engine Headless plugin and set WP_HEADLESS_SECRET to the “Secret Key” from Settings → Headless to enable post previews.',
   );
 }