Skip to content
This repository was archived by the owner on Feb 27, 2024. It is now read-only.

Commit 261c37f

Browse files
gregrickabygregrickaby
committed
major overhaul of README geared toward the general public
1 parent 72d2c11 commit 261c37f

File tree

1 file changed

+144
-80
lines changed

1 file changed

+144
-80
lines changed

‎README.md

Lines changed: 144 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,179 +1,243 @@
11
# Next.js WordPress Starter <!-- omit in toc -->
22

3-
WebDevStudios fork of the [official Next.js WordPress Example](https://github.com/vercel/next.js/tree/canary/examples/cms-wordpress). Used as a starter for headless WordPress projects.
3+
WebDevStudios fork of the official Next.js WordPress [example](https://github.com/vercel/next.js/tree/canary/examples/cms-wordpress). Used as a starter for headless WordPress projects.
44

5-
👉 https://nextjs-wordpress-starter.vercel.app
5+
**This project is still in active development. Use at your own risk.**
6+
7+
https://nextjs-wordpress-starter-staging.vercel.app/
68

79
<a href="https://webdevstudios.com/contact/"><img src="https://webdevstudios.com/wp-content/uploads/2018/04/wds-github-banner.png" alt="WebDevStudios. Your Success is Our Mission."></a>
810

911
## 🗂 Table of Contents <!-- omit in toc -->
1012

11-
- [🎓 Preface](#-preface)
13+
- [🎓 Overview](#-overview)
14+
- [Why?](#why)
15+
- [How's this all work?](#hows-this-all-work)
16+
- [🚀 Frontend Setup (Next.js)](#-frontend-setup-nextjs)
1217
- [Dependencies](#dependencies)
13-
- [Git Branches](#git-branches)
14-
- [Credentials](#credentials)
15-
- [🚀 Front-end Setup (Next.js)](#-front-end-setup-nextjs)
16-
- [Clone this repository](#clone-this-repository)
17-
- [Link Project with Vercel](#link-project-with-vercel)
18-
- [Install Front-end](#install-front-end)
19-
- [Start Dev Server](#start-dev-server)
20-
- [🔧 Back-end Setup (WordPress)](#-back-end-setup-wordpress)
21-
- [Setup Local](#setup-local)
22-
- [Migrate DB Pro](#migrate-db-pro)
23-
- [Copy WP Engine Environments](#copy-wp-engine-environments)
24-
- [💻 Development](#-development)
18+
- [Install](#install)
19+
- [🔧 Backend Setup (WordPress)](#-backend-setup-wordpress)
20+
- [Dependencies](#dependencies-1)
21+
- [Install](#install-1)
22+
- [💻 Frontend Development](#-frontend-development)
2523
- [Git Workflow](#git-workflow)
2624
- [Deployments](#deployments)
2725
- [Storybook](#storybook)
26+
- [WebDevStudios Specific Info](#webdevstudios-specific-info)
27+
- [WordPress Github](#wordpress-github)
28+
- [WP Engine](#wp-engine)
2829
- [Chromatic](#chromatic)
30+
- [1Password](#1password)
31+
- [Migrate DB Pro](#migrate-db-pro)
32+
- [Copy WP Engine Environments](#copy-wp-engine-environments)
2933
- [:octocat: Contributing](#octocat-contributing)
3034

3135
---
3236

33-
## 🎓 Preface
37+
## 🎓 Overview
3438

35-
### Dependencies
39+
### Why?
3640

37-
You will need the following dependencies installed on your computer:
41+
It's easy to query a WordPress REST-API and map over some blog posts in JavaScript. That's where many examples on the Internet stop and you'd be hard pressed to find anything about supporting advanced features because **_headless WordPress is hard!_**
3842

39-
- [Node 12](https://nodejs.org/en/)
40-
- [Yarn](https://yarnpkg.com/)
41-
- [Vercel CLI](https://vercel.com/download)
43+
At WebDevStudios we believe that WordPress is so much more than a blog-- and our clients require support for things like: SEO, forms, post previews, search, comments, authentication, custom post types, custom fields, etc...
4244

43-
### Git Branches
45+
With this starter, we've figured out "the hard stuff" and placed the sum of our knowledge into something the community (and our future projects) could use as a jumping off point.
4446

45-
- `develop` - auto deploys on Vercel
46-
- `staging` - auto deploys on Vercel
47-
- `main` - auto deploys on Vercel
48-
- `Pull Requests` - deployment previews are automatically generated by Vercel
47+
### How's this all work?
4948

50-
### Credentials
49+
The frontend (Next.js) talks to the backend (WordPress) via GraphQL.
5150

52-
- Credentials are in 1password --> Next.js Starter --> WordPress
51+
<details>
52+
<img src="https://dl.dropbox.com/s/9wsal7szatfwt6g/nextjs-wordpress-starter-frontend-backend-graphic.png?dl=0" alt="A graphic showing the relationship between environments">
53+
</details>
5354

5455
---
5556

56-
## 🚀 Front-end Setup (Next.js)
57+
## 🚀 Frontend Setup (Next.js)
5758

58-
The following instructions will standup a local install of Next.js (front-end). It queries data from WordPress (back-end).
59+
The following steps will stand up a local install of Next.js.
5960

60-
### Clone this repository
61+
### Dependencies
6162

62-
```bash
63-
git clone [email protected]:WebDevStudios/nextjs-wordpress-starter.git
64-
```
63+
Before you get started, make sure you have the following dependencies installed on your computer:
6564

66-
### Link Project with Vercel
65+
- [Node 12](https://nodejs.org/en/)
66+
- [Yarn](https://yarnpkg.com/)
67+
- [Vercel CLI](https://vercel.com/download)
6768

68-
If this step fails, you'll most likely need be added to the WDS Team in Vercel first. Learn more about [Project Linking](https://vercel.com/docs/cli#commands/overview/project-linking) with the Vercel CLI.
69+
### Install
6970

70-
Install the [Vercel CLI](https://vercel.com/download):
71+
**Step 1: Clone the repo**
7172

7273
```bash
73-
npm i -g vercel
74+
git clone [email protected]:WebDevStudios/nextjs-wordpress-starter.git
7475
```
7576

76-
Change directories into this project:
77+
**Step 2: Change directories**
7778

7879
```bash
7980
cd nextjs-wordpress-starter
8081
```
8182

82-
Initialize Vercel by answering the questions in the command line when prompted:
83+
**Step 3: Install dependencies**
8384

8485
```bash
85-
vercel
86+
yarn
8687
```
8788

88-
### Install Front-end
89+
**Step 4: Setup ENV Variables**
8990

90-
Pull down the ENV vars from Vercel:
91+
Copy the sample ENV file, then add your credentials:
9192

9293
```bash
93-
vercel env pull
94+
cp .env.sample .env
9495
```
9596

96-
Install dependencies:
97+
--OR--
98+
99+
[Link the project with Vercel](https://vercel.com/docs/cli#commands/overview/project-linking), then pull down the ENV variables:
100+
101+
<details>
102+
103+
The following steps require A) access to a Vercel account and B) assumes the ENV vars are already set up on Vercel. If you need access to the WDS Team account on Vercel, please reach out to Greg.
104+
105+
**Step 1: Install the [Vercel CLI](https://vercel.com/download)**
97106

98107
```bash
99-
yarn
108+
npm i -g vercel
109+
```
110+
111+
**Step 2: Initialize Vercel**
112+
113+
```bash
114+
vercel init
100115
```
101116

102-
### Start Dev Server
117+
Answer the questions in the command line when prompted.
118+
119+
**Step 3: Pull down the ENV variables**
103120

104121
```bash
105-
yarn dev
122+
vercel env pull
106123
```
107124

108-
The frontend is now available at http://localhost:3000
125+
</details>
109126

110127
---
111128

112-
## 🔧 Back-end Setup (WordPress)
129+
## 🔧 Backend Setup (WordPress)
113130

114-
The backend is hosted at WP Engine. There are 3 environments...please use Develop for working locally.
131+
The following steps will stand up a local install of WordPress.
115132

116-
- [Develop](https://nextjsdevstart.wpengine.com/wp-admin/)
117-
- [Staging](https://nextjsstgstart.wpengine.com/wp-admin/)
118-
- [Production](https://nextjs.wpengine.com/wp-admin)
133+
### Dependencies
119134

120-
**Note: There is no frontend for WordPress** - But it is running [wd_s](https://github.com/WebDevStudios/wd_s) which houses `/acf-json` and other functions.
135+
Before you get started, make sure you have the following dependency installed on your computer:
121136

122-
### Setup Local
137+
- [Local WP](https://localwp.com/)
123138

124-
There is an [Local export available](https://drive.google.com/drive/folders/1Ju81KThAUHOuWRNslw_m7xZScwoJYkr0). Simply import the `nextjs-wp-XX.XX.XX.zip` file and you can tinker with the WordPress backend.
139+
### Install
125140

126-
### Migrate DB Pro
141+
**Step 1: Download the Local WP export**
127142

128-
You can use Migrate DB Pro to pull databases and files. **Please see 1password --> Next.js Starter --> Migrate DB Pro**
143+
- [nextjs-wp-01.29.2021.zip (162MB)](https://drive.google.com/file/d/1iTVxyTS6ezy6RUhba9CbAjZL1x3iZyv7/view?usp=sharing)
129144

130-
### Copy WP Engine Environments
145+
**Step 2: Import the .zip**
131146

132-
WP Engine supports [copying environments](https://wpengine.com/support/copy-site/). For example, to copy Develop --> Staging:
147+
- https://localwp.com/help-docs/getting-started/how-to-import-a-wordpress-site-into-local/
133148

134-
1. Log into the WP Engine [User Portal](https://my.wpengine.com/sites)
135-
2. Click on [Nextjsstgstart](https://my.wpengine.com/installs/nextjsstgstart)
136-
3. In the top right corner, click the "Copy environment" button
137-
4. Select the options:
138-
![screenshot](https://dl.dropbox.com/s/uvzm2trqbgbpyky/Screen%20Shot%202020-12-21%20at%2011.19.34%20AM.png?dl=0)
139-
5. Click "Preview copy" and a modal will appear to let you verify the options
140-
6. Click "Copy environment"
149+
**Step 3: Start the `nextjs-wp` site**
150+
151+
**Note:** Make sure your Local URL matches the `LOCAL_WORDPRESS_API_URL` in the frontend `.env` file!
141152

142153
---
143154

144-
## 💻 Development
155+
## 💻 Frontend Development
145156

146157
### Git Workflow
147158

148159
1. Create a `feature` branch off `staging`
149-
2. Open a draft Pull Request on Github
150-
3. When finished with your work, fill out the PR template and publish your PR
151-
4. Vercel will create a deployment preview. It must pass and deploy successfully
152-
5. After peer review, PR will be merged back into `staging`
153-
6. Repeat ♻️
160+
2. Work locally adhereing to coding standards
161+
3. When ready, open a draft Pull Request on Github
162+
4. When finished, fill out the PR template and publish your PR
163+
5. Your PR must pass assertions and deploy successfully
164+
6. After peer review, the PR will be merged back into `staging`
165+
7. Repeat ♻️
154166

155167
### Deployments
156168

157-
[Vercel](https://nextjs-wordpress-starter-gregrickaby.webdevstudios.vercel.app) is connected to this Github repository and automatically builds and deploys. Learn more about [Vercel + Github integration](https://vercel.com/docs/git/vercel-for-github).
169+
[Vercel](https://nextjs-wordpress-starter-gregrickaby.webdevstudios.vercel.app) is connected to this Github repository and will automatically build and deploy. Learn more about [Vercel + Github integration](https://vercel.com/docs/git/vercel-for-github).
158170

159171
### Storybook
160172

161-
To view this project's storybook on your Local:
173+
To work with Storybook on your Local, run the following command:
162174

163175
```bash
164176
yarn storybook
165177
```
166178

167-
View this project's [Storybook](https://staging--5fe0becf19ad53002147b034.chromatic.com/)
179+
Stories are written in `.mdx` and should be placed next to the component. Learn more about [Storybook](https://storybook.js.org/).
180+
181+
## WebDevStudios Specific Info
182+
183+
The following information pertains to internal tools and workflows at WebDevStudios.
184+
185+
<details>
186+
187+
### WordPress Github
188+
189+
There is a Github repo for the backend. This repo manages plugins and the headless theme. Future projects should probably mimic this setup:
190+
191+
https://github.com/WebDevStudios/nextjs-starter-wordpress
192+
193+
**Note: There is no frontend for WordPress** - But it is running a headless theme which houses `/acf-json` and other headless-related functions.
194+
195+
### WP Engine
196+
197+
There are 3 WordPress environments on WP Engine:
198+
199+
- [Develop](https://nextjsdevstart.wpengine.com/wp-admin/)
200+
- [Staging](https://nextjsstgstart.wpengine.com/wp-admin/)
201+
- [Production](https://nextjs.wpengine.com/wp-admin)
202+
203+
Use the orange "WebDevStudios Login" button to log in.
168204

169205
### Chromatic
170206

171-
This project supports UI review via Chromatic, which is trigger via Github Actions.
207+
This project supports UI review via Chromatic, which is triggered via Github Actions.
208+
209+
View this project's [Chromatic](https://chromatic.com/library?appId=5fe0becf19ad53002147b034&branch=staging) by logging in with your WDS Github account.
210+
211+
### 1Password
212+
213+
All of the credentials are in the following vault:
214+
215+
```text
216+
1Password --> Next.js Starter
217+
```
218+
219+
### Migrate DB Pro
220+
221+
You can use Migrate DB Pro to pull databases and files. Please see 1password for credentials
222+
223+
### Copy WP Engine Environments
224+
225+
WP Engine supports [copying environments](https://wpengine.com/support/copy-site/). This should be done at the end of two week sprints (or as needed).
226+
227+
**The following steps will copy Develop to Staging:**
228+
229+
1. Log into the WP Engine [User Portal](https://my.wpengine.com/sites)
230+
2. Click on [Nextjsstgstart](https://my.wpengine.com/installs/nextjsstgstart)
231+
3. In the top right corner, click the "Copy environment" button
232+
4. Select the options:
233+
![screenshot](https://dl.dropbox.com/s/uvzm2trqbgbpyky/Screen%20Shot%202020-12-21%20at%2011.19.34%20AM.png?dl=0)
234+
5. Click "Preview copy" and a modal will appear to let you verify the options
235+
6. Click "Copy environment"
172236

173-
View this project's [Chromatic](https://chromatic.com/library?appId=5fe0becf19ad53002147b034&branch=staging)
237+
</details>
174238

175239
---
176240

177241
## :octocat: Contributing
178242

179-
Your [contributions](https://github.com/WebDevStudios/nextjs-wordpress-starter/blob/main/.github/CONTRIBUTING.md) and issues are welcome.
243+
[Contributions](https://github.com/WebDevStudios/nextjs-wordpress-starter/blob/main/.github/CONTRIBUTING.md) are welcome. 🍻

0 commit comments

Comments
 (0)