feat: Point getting-started to a live demo URL for a faster new user experience (BH-895)

README.md

@@ -11,14 +11,30 @@ _🚧 **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/)!
+### 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`
+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.
-4. 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`
-6. `cp .env.local.sample .env.local`
-7. Populate `WORDPRESS_URL` in `.env.local` with the full URL to your WordPress site, including the `http://` or `https://` prefix.
-8. Populate `WP_HEADLESS_SECRET` in `.env.local` with the secret key found at Settings → Headless in your WordPress admin area.
-9. `cd my-app && npm run dev`
+
+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)
+
+You'll see the same site with your WordPress posts instead of ours.
 
 ➡️ [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.',
   );
 }