From 5c9f32c0b4c5223dcd435382eb1d9a3a6fa3e1d9 Mon Sep 17 00:00:00 2001 From: Nick Cernis Date: Thu, 25 Feb 2021 13:20:50 +0100 Subject: [PATCH] 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 | 34 ++++++++---- docs/getting-started/README.md | 54 +++++++++++-------- examples/getting-started/.env.local.sample | 4 +- .../getting-started/components/Header.tsx | 3 +- packages/headless/src/api/apolloClient.ts | 8 +-- packages/headless/src/auth/authorize.ts | 4 +- 6 files changed, 68 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 51e8a2f03..b5f8ba50a 100644 --- a/README.md +++ b/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/) diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md index cab54f347..1b4e57865 100644 --- a/docs/getting-started/README.md +++ b/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 diff --git a/examples/getting-started/.env.local.sample b/examples/getting-started/.env.local.sample index 78b29f5b6..92cb7d7e9 100644 --- a/examples/getting-started/.env.local.sample +++ b/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 diff --git a/examples/getting-started/components/Header.tsx b/examples/getting-started/components/Header.tsx index fd29614b1..c5a141955 100644 --- a/examples/getting-started/components/Header.tsx +++ b/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', diff --git a/packages/headless/src/api/apolloClient.ts b/packages/headless/src/api/apolloClient.ts index e8fc6c33f..4436c4b6d 100644 --- a/packages/headless/src/api/apolloClient.ts +++ b/packages/headless/src/api/apolloClient.ts @@ -15,14 +15,16 @@ import { CookieOptions, getAccessToken } from '../auth'; export type PersistentContext = Record; -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.', ); } } diff --git a/packages/headless/src/auth/authorize.ts b/packages/headless/src/auth/authorize.ts index d9cedfb16..6e4b2fe88 100644 --- a/packages/headless/src/auth/authorize.ts +++ b/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.', ); }