Update Faust.js tutorial example setup and docs

Added .wp-env.json and supporting wp-env files for improved local WordPress setup. Updated README with detailed setup instructions and commands. Changed default WordPress port in .env.local.example. Removed obsolete faust-tutorial-blueprint.json. Updated dependencies in package.json and package-lock.json. Improved tutorial documentation in docs/tutorial/learn-faust/index.md.

Author: josephfusco

archive/examples/next/tutorial/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "faust-tutorial",
+	"version": "0.1.0",
+	"private": true,
+	"license": "0BSD",
+	"scripts": {
+		"dev": "next dev --turbopack",
+		"build": "next build",
+		"generate": "faust generatePossibleTypes",
+		"start": "next start",
+		"lint": "next lint",
+		"tutorial:start": "npm run wp:start && npm run dev",
+		"tutorial:stop": "npm run wp:stop",
+		"tutorial:setup": "npm install && npm run wp:start && npm run wp:db:import",
+		"tutorial:prune": "npm run wp:destroy && npm run tutorial:setup && npm run tutorial:start",
+		"wp:start": "npm install && wp-env start",
+		"wp:stop": "wp-env stop",
+		"wp:destroy": "wp-env destroy",
+		"wp:db:query": "wp-env run cli -- wp db query",
+		"wp:db:export": "wp-env run cli -- wp db export /var/www/html/db/database.sql",
+		"wp:db:import": "wp-env run cli -- wp db import /var/www/html/db/database.sql",
+		"wp-env": "wp-env"
+	},
+	"dependencies": {
+		"@apollo/client": "^3.13.9",
+		"@faustwp/blocks": "^6.1.3",
+		"@faustwp/cli": "^3.2.4",
+		"@faustwp/core": "^3.2.4",
+		"graphql": "^16.11.0",
+		"next": "^15.4.5",
+		"next-secure-headers": "^2.2.0",
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0"
+	},
+	"devDependencies": {
+		"@eslint/eslintrc": "^3.3.1",
+		"@wordpress/env": "^10.35.0",
+		"eslint": "^9.32.0",
+		"eslint-config-next": "15.1.6",
+		"postcss": "^8",
+		"tailwindcss": "^3.4.1"
+	},
+	"overrides": {
+		"@babel/runtime": "^7.26.10"
+	}
+}

docs/tutorial/learn-faust/index.md

@@ -20,7 +20,7 @@ In order to complete this tutorial, you should:
 - Be comfortable running commands on the [command line](https://en.wikipedia.org/wiki/Command-line_interface)
 - Have [Node.js and NPM](https://nodejs.org/) installed on your computer
 
-You should also not have any other projects running on port `3000` or `8881`, since the links in this tutorial point to pages on those ports.
+You should also not have any other projects running on port `3000` or `8888`, since the links in this tutorial point to pages on those ports. You'll also need [Docker](https://www.docker.com/) installed and running to use wp-env for the WordPress backend.
 
 ## Set up
 
@@ -39,12 +39,12 @@ npx degit wpengine/faustjs/examples/next/tutorial faust-tutorial
 Initial set up steps:
 
 - `cd` into the `/faust-tutorial` project folder.
-- Run `npm run wp-dev`. This command uses the [`wp-now`](https://www.npmjs.com/package/@wp-now/wp-now) NPM package and the included [`faust-tutorial-blueprint.json`](https://github.com/wpengine/faustjs/blob/canary/examples/next/tutorial/faust-tutorial-blueprint.json) blueprint file to set up a local WordPress environment.
-- When asked if it's okay to install the `@wp-now/wp-now` package, answer `y` to confirm.
+- Run `npm run tutorial:setup`. This command uses [`wp-env`](https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-wp-env/) to set up a local WordPress environment with Docker. The configuration is defined in the `.wp-env.json` file included in the project.
+- The setup process will install dependencies, start the WordPress environment, and import a pre-configured database.
 
 After a moment, you should have a WordPress site up-and-running.
 
-By navigating to http://localhost:8881/wp-admin/plugins.php, You can see that the required [FaustWP](https://wordpress.org/plugins/faustwp/) and [WPGraphQL](https://wordpress.org/plugins/wp-graphql/) plugins have already been installed for you.
+By navigating to http://localhost:8888/wp-admin/plugins.php, you can see that the required [FaustWP](https://wordpress.org/plugins/faustwp/) and [WPGraphQL](https://wordpress.org/plugins/wp-graphql/) plugins have already been installed for you.
 
 Next, we'll just configure a few last things in WordPress.
 
@@ -70,7 +70,7 @@ Follow these steps to set up your Faust.js frontend:
 
 ```env title=".env.local"
 # Your WordPress site URL
-NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8881
+NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888
 
 # Plugin secret found in WordPress Settings->Faust
 FAUST_SECRET_KEY=ABC123
@@ -166,7 +166,7 @@ export default templates;
 
 This tells Faust to use the `PageTemplate` component as the template to render pages that match `page`, according to the template hierarchy.
 
-Save your changes and visit [http://localhost:3000/sample-page/](http://localhost:3000/sample-page/) in a browser. You should be able to see the title and content for the [Sample Page page in WordPress](http://localhost:8881/wp-admin/post.php?post=2&action=edit).
+Save your changes and visit [http://localhost:3000/sample-page/](http://localhost:3000/sample-page/) in a browser. You should be able to see the title and content for the [Sample Page page in WordPress](http://localhost:8888/wp-admin/post.php?post=2&action=edit).
 
 Now that you understand how to leverage the template hierarchy, you can follow this pattern to add additional page templates:
 
@@ -381,7 +381,7 @@ You should now be able to visit http://localhost:3000/blog/hello-world/ and see
 
 Inspect the blog post content in the browser dev tools and notice that each block is being rendered and that only the paragraph blocks are wrapped in a `div` with a class name of `paragraph-block-wrapper`. Currently, we're not leveraging the `paragraph-block-wrapper` class in any way, but you can see the potential here. By being able to query for and render blocks individually, you have the ability to wrap specific blocks in arbitrary markup, override specific blocks with custom implementations, and more.
 
-Now [edit the Hello World! blog post](http://localhost:8881/wp-admin/post.php?post=1&action=edit). Make several changes to it in terms of font size, padding, margin, a border, an HTML anchor, and additional CSS classes, then save your changes.
+Now [edit the Hello World! blog post](http://localhost:8888/wp-admin/post.php?post=1&action=edit). Make several changes to it in terms of font size, padding, margin, a border, an HTML anchor, and additional CSS classes, then save your changes.
 
 Reload the http://localhost:3000/blog/hello-world/ page in your frontend app and see that all the changes you applied are now being reflected. Inspect the paragraph block in DevTools to see markup similar to the example below. You can see that Faust has taken care of rendering the paragraph tag to include these attributes, and even loaded the CSS required to apply the correct styles.
 

examples/next/tutorial/.env.local.example

@@ -1,5 +1,5 @@
 # Your WordPress site URL
-NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8881
+NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8888
 
 # Plugin secret found in WordPress Settings->Faust
 FAUST_SECRET_KEY=

examples/next/tutorial/.wp-env.json

@@ -0,0 +1,23 @@
+{
+  "phpVersion": "8.3",
+  "plugins": [
+    "https://github.com/wp-graphql/wp-graphql/releases/latest/download/wp-graphql.zip",
+    "https://downloads.wordpress.org/plugin/faustwp.latest-stable.zip"
+  ],
+  "config": {
+    "WP_DEBUG": true,
+    "SCRIPT_DEBUG": false,
+    "GRAPHQL_DEBUG": true,
+    "WP_DEBUG_LOG": true,
+    "WP_DEBUG_DISPLAY": false,
+    "SAVEQUERIES": false
+  },
+  "mappings": {
+    "db": "./wp-env/db",
+    "wp-content/uploads": "./wp-env/uploads",
+    ".htaccess": "./wp-env/setup/.htaccess"
+  },
+  "lifecycleScripts": {
+    "afterStart": "wp-env run cli -- wp rewrite structure '/blog/%postname%/' && wp-env run cli -- wp rewrite flush"
+  }
+}

examples/next/tutorial/README.md

@@ -1,3 +1,74 @@
 # Learn Faust.js
 
 Next.js app to be used with the [Learn Faust tutorial](https://faustjs.org/docs/tutorial/learn-faust/).
+
+## Prerequisites
+
+- Node.js (v18+ recommended)
+- [Docker](https://www.docker.com/) (required for running WordPress with wp-env)
+
+**Note:** Make sure Docker is running before starting (`docker ps`)
+
+## Quick Start
+
+1. **Install dependencies**
+   ```bash
+   npm install
+   ```
+
+2. **Set up environment variables**
+
+   Copy the example file and configure:
+   ```bash
+   cp .env.local.example .env.local
+   ```
+
+3. **Start WordPress and the development server**
+   ```bash
+   npm run tutorial:setup    # First time setup
+   npm run tutorial:start    # Start WordPress and Next.js dev server
+   ```
+
+4. **Access the application**
+   - Frontend: [http://localhost:3000/](http://localhost:3000/)
+   - WordPress Admin: [http://localhost:8888/wp-admin/](http://localhost:8888/wp-admin/)
+
+   > **Default credentials:** username: `admin`, password: `password`
+
+5. **Configure Faust in WordPress**
+
+   Follow the tutorial at [faustjs.org/docs/tutorial/learn-faust/](https://faustjs.org/docs/tutorial/learn-faust/) to complete the setup.
+
+## Available Commands
+
+| Command            | Description                                                    |
+| ------------------ | -------------------------------------------------------------- |
+| `tutorial:setup`   | Initial setup: installs packages, starts wp-env, imports DB   |
+| `tutorial:start`   | Starts WordPress and the Next.js development server           |
+| `tutorial:stop`    | Stops the WordPress environment                                |
+| `tutorial:prune`   | Rebuilds everything from scratch                               |
+| `wp:start`         | Starts the WordPress environment                               |
+| `wp:stop`          | Stops the WordPress environment                                |
+| `wp:destroy`       | Completely removes the WordPress environment                   |
+| `wp:db:query`      | Executes a database query within the WordPress environment     |
+| `wp:db:export`     | Exports the WordPress database to `wp-env/db/database.sql`    |
+| `wp:db:import`     | Imports the WordPress database from `wp-env/db/database.sql`  |
+| `dev`              | Runs the Next.js development server only                       |
+| `build`            | Builds the Next.js application for production                  |
+
+## Project Structure
+
+```
+├── src                                # Next.js application source
+├── .wp-env.json                       # wp-env configuration file
+└── wp-env
+    ├── db
+    │   └── database.sql               # WordPress database with pre-configured settings
+    ├── setup
+    │   └── .htaccess                  # CORS configuration
+    └── uploads                        # WordPress uploads directory
+```
+
+## Learn More
+
+For detailed step-by-step instructions, visit the [Learn Faust tutorial](https://faustjs.org/docs/tutorial/learn-faust/).