rtCamp · justlevine · Mar 25, 2025 · Mar 2, 2025 · Mar 2, 2025 · Mar 2, 2025
diff --git a/.changeset/eleven-experts-feel.md b/.changeset/eleven-experts-feel.md
@@ -0,0 +1,23 @@
+---
+"@snapwp/blocks": minor
+"@snapwp/query": minor
+"@snapwp/types": minor
+"@snapwp/core": minor
+"@snapwp/next": minor
+"snapwp": minor
+---
+
+feat!: Add and improve robust WordPress and internal URI handling.
+
+**Breaking Changes:**
+
+The [Environment Variables and Config API](../docs/config-api.md) have been updated, with many of the variables renamed or removed. Please review the updated documentation for the latest changes.
+
+| Old value | Replace with |
+|----------|----------|
+| NEXT_PUBLIC_URL | NEXT_PUBLIC_FRONTEND_URL |
+| NEXT_PUBLIC_WORDPRESS_URL | NEXT_PUBLIC_WP_HOME_URL |
+| NEXT_PUBLIC_WORDPRESS_UPLOADS_PATH | NEXT_PUBLIC_WP_UPLOADS_DIRECTORY |
+| NEXT_PUBLIC_WORDPRESS_REST_URL_PREFIX | NEXT_PUBLIC_REST_URL_PREFIX |
+| getConfig().nextUrl | getConfig().frontendUrl |
+| getConfig().homeUrl | getConfig().wpHomeUrl |
diff --git a/.changeset/salty-moments-yell.md b/.changeset/salty-moments-yell.md
@@ -0,0 +1,5 @@
+---
+"@snapwp/core": minor
+---
+
+dev!: Reorganize core `utils` into type-based subdirectories.
diff --git a/.env.example b/.env.example
@@ -1,20 +1,27 @@
-# Enable if connecting to a self-signed cert
+# Enable if connecting to a self-signed cert.
 # NODE_TLS_REJECT_UNAUTHORIZED=0
 
-# The headless frontend domain URL. Uncomment this line and ensure the value matches the URL used by your frontend app.
-# NEXT_PUBLIC_URL=http://localhost:3000
+# The URL of the Next.js "headless" frontend.
+NEXT_PUBLIC_FRONTEND_URL=http://localhost:3000
 
-# The WordPress "frontend" domain URL
-NEXT_PUBLIC_WORDPRESS_URL=https://headless-demo.local
+# The traditional WordPress frontend domain URL. E.g. https://my-headless-site.local
+NEXT_PUBLIC_WP_HOME_URL=
 
-# The WordPress GraphQL endpoint
+# The backend "WordPress Address" URL where your WordPress core files reside.
+# Only needed if different than `NEXT_PUBLIC_WP_HOME_URL`. E.g. https://my-headless-site.local/wp/
+# NEXT_PUBLIC_WP_SITE_URL=
+
+# The WordPress GraphQL endpoint.
 NEXT_PUBLIC_GRAPHQL_ENDPOINT=graphql
 
-# The WordPress Uploads directory path
-# NEXT_PUBLIC_WORDPRESS_UPLOADS_PATH=/wp-content/uploads
+# The WordPress REST API URL prefix.
+# NEXT_PUBLIC_REST_URL_PREFIX=/wp-json
+
+# The relative path to the WordPress uploads directory.
+# NEXT_PUBLIC_WP_UPLOADS_DIRECTORY=/wp-content/uploads
 
-# The WordPress REST URL Prefix
-# NEXT_PUBLIC_WORDPRESS_REST_URL_PREFIX=/wp-json
+# The CORS proxy prefix to use when bypassing CORS restrictions from WordPress server. If unset, no proxy will be used.
+# NEXT_PUBLIC_CORS_PROXY_PREFIX=/proxy
 
-# Token used for authenticating GraphQL introspection queries
+# Token used for authenticating GraphQL introspection queries.
 INTROSPECTION_TOKEN=
diff --git a/.github/workflows/pull_request_examples.yml b/.github/workflows/pull_request_examples.yml
@@ -99,15 +99,18 @@ jobs:
                   npm run --if-present build
 
             - name: Install dependencies
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
+              run: npm install
+
+            - name: Copy .env.example to .env
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
               run: |
-                  cd '${{ github.workspace }}/examples/${{ matrix.example }}'
-                  npm install
                   cp .env.example .env
+                  sed -i 's|NEXT_PUBLIC_WP_HOME_URL=.*|NEXT_PUBLIC_WP_HOME_URL=http://localhost|' .env
 
             - name: Run ESLint
-              run: |
-                  cd '${{ github.workspace }}/examples/${{ matrix.example }}'
-                  npm run --if-present lint
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
+              run: npm run --if-present lint
 
     typecheck:
         name: TS Typecheck
@@ -148,16 +151,23 @@ jobs:
                   npm run --if-present build
 
             - name: Install dependencies
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
+              run: npm install
+
+            - name: Copy .env.example to .env
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
               run: |
-                  cd '${{ github.workspace }}/examples/${{ matrix.example }}'
-                  npm install
                   cp .env.example .env
-                  npm run codegen
+                  sed -i 's|NEXT_PUBLIC_WP_HOME_URL=.*|NEXT_PUBLIC_WP_HOME_URL=http://localhost|' .env
+
+            - name: Run Codegen
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
+              run: npm run codegen
 
             - name: Run TypeScript type check
               # TODO: Why are we catching the error?
-              run: |
-                  npm run --if-present typecheck
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
+              run: npm run --if-present typecheck
 
     test-build:
         name: Test Build (Node v${{ matrix.node-version }} | ${{ matrix.example }})
@@ -240,15 +250,18 @@ jobs:
                   npm run --if-present build
 
             - name: Install dependencies
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
+              run: npm install
+
+            - name: Copy .env.example to .env
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
               run: |
-                  cd '${{ github.workspace }}/examples/${{ matrix.example }}'
-                  npm install
                   cp .env.example .env
+                  sed -i 's|NEXT_PUBLIC_WP_HOME_URL=.*|NEXT_PUBLIC_WP_HOME_URL=http://localhost|' .env
 
             - name: Build assets
-              run: |
-                  cd '${{ github.workspace }}/examples/${{ matrix.example }}'
-                  npm run --if-present build
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
+              run: npm run --if-present build
 
     unit:
         name: Unit Tests (Node v${{ matrix.node-version }} | ${{ matrix.example }})
@@ -290,15 +303,18 @@ jobs:
                   npm run --if-present build
 
             - name: Install dependencies
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
+              run: npm install
+
+            - name: Copy .env.example to .env
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
               run: |
-                  cd '${{ github.workspace }}/examples/${{ matrix.example }}'
-                  npm install
                   cp .env.example .env
+                  sed -i 's|NEXT_PUBLIC_WP_HOME_URL=.*|NEXT_PUBLIC_WP_HOME_URL=http://localhost|' .env
 
             - name: Run unit tests
-              run: |
-                  cd '${{ github.workspace }}/examples/${{ matrix.example }}'
-                  npm run --if-present test
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
+              run: npm run --if-present test
 
     security:
         name: Dependencies Audit
@@ -339,15 +355,18 @@ jobs:
                   npm run --if-present build
 
             - name: Install dependencies
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
+              run: npm install
+
+            - name: Copy .env.example to .env
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
               run: |
-                  cd '${{ github.workspace }}/examples/${{ matrix.example }}'
-                  npm install
                   cp .env.example .env
+                  sed -i 's|NEXT_PUBLIC_WP_HOME_URL=.*|NEXT_PUBLIC_WP_HOME_URL=http://localhost|' .env
 
             - name: Run npm audit
-              run: |
-                  cd '${{ github.workspace }}/examples/${{ matrix.example }}'
-                  npm audit --audit-level=high
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
+              run: npm audit --audit-level=high
 
     prettier:
         name: Check Formatting
@@ -388,12 +407,15 @@ jobs:
                   npm run --if-present build
 
             - name: Install dependencies
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
+              run: npm install
+
+            - name: Copy .env.example to .env
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
               run: |
-                  cd '${{ github.workspace }}/examples/${{ matrix.example }}'
-                  npm install
                   cp .env.example .env
+                  sed -i 's|NEXT_PUBLIC_WP_HOME_URL=.*|NEXT_PUBLIC_WP_HOME_URL=http://localhost|' .env
 
             - name: Run Prettier
-              run: |
-                  cd '${{ github.workspace }}/examples/${{ matrix.example }}'
-                  npm run --if-present format-check
+              working-directory: ${{ github.workspace }}/examples/${{ matrix.example }}
+              run: npm run --if-present format-check
diff --git a/docs/config-api.md b/docs/config-api.md
@@ -15,16 +15,16 @@ SnapWP uses the following `.env` variables to configure your Next.js app.
 > We recommend copying the `.env` variables from the SnapWP Helper plugin settings screen and pasting them into your `.env` file, then modifying them as needed.
 > See the [Getting Started](getting-started.md#backend-setup) guide for more information.
 
-| Variable                                | Required | Default Value                            | Description                                                                       | Available via `getConfig() |
-| --------------------------------------- | -------- | ---------------------------------------- | --------------------------------------------------------------------------------- | -------------------------- |
-| `NEXT_PUBLIC_URL`                       | Yes      |                                          | The URL of the Next.js site.                                                      | `nextUrl`                  |
-| `NEXT_PUBLIC_WORDPRESS_URL`             | Yes      |                                          | The WordPress frontend domain URL.                                                | `homeUrl`                  |
-| `INTROSPECTION_TOKEN`                   | Yes      |                                          | Token used for authenticating GraphQL introspection queries with GraphQL Codegen. | N/A                        |
-| `NEXT_PUBLIC_GRAPHQL_ENDPOINT`          | No       | `index.php?graphql`                      | The relative path to the WordPress GraphQL endpoint.                              | `graphqlEndpoint`          |
-| `NEXT_PUBLIC_WORDPRESS_UPLOADS_PATH`    | No       | `/wp-content/uploads`                    | The relative path to the WordPress uploads directory.                             | `uploadsDirectory`         |
-| `NEXT_PUBLIC_WORDPRESS_REST_URL_PREFIX` | No       | `/wp-json`                               | The WordPress REST API URL prefix.                                                | `restUrlPrefix`            |
-| `NEXT_PUBLIC_USE_CORS_PROXY`            | No       | `process.env.NODE_ENV === 'development'` | Whether to use a CORS proxy for the WordPress API.                                | `useCorsProxy`             |
-| `NEXT_PUBLIC_CORS_PROXY_PREFIX`         | No       | `/proxy`                                 | The prefix of the CORS proxy.                                                     | `corsProxyPrefix`          |
+| Variable                           | Required | Default Value         | Description                                                                                                                                                                                      | Available via `getConfig() |
+| ---------------------------------- | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
+| `NEXT_PUBLIC_FRONTEND_URL`         | Yes      |                       | The URL of the Next.js (headless) frontend. <br />E.g. `http://localhost:3000`                                                                                                                   | `frontendUrl`              |
+| `NEXT_PUBLIC_WP_HOME_URL`          | Yes      |                       | The traditional WordPress _frontend_ domain URL. <br />E.g `https://mywpsite.local`                                                                                                              | `wpHomeUrl`                |
+| `NEXT_PUBLIC_WP_SITE_URL`          | No       |                       | The _backend_ "WordPress Address" domain URL where your WordPress core files reside.<br />Only necessary if different than `NEXT_PUBLIC_WP_HOME_URL`<br />E.g. `https://api.mywpsite.local/wp` . | `wpSiteUrl`                |
+| `NEXT_PUBLIC_GRAPHQL_ENDPOINT`     | No       | `index.php?graphql`   | The relative path to the WordPress GraphQL endpoint.                                                                                                                                             | `graphqlEndpoint`          |
+| `NEXT_PUBLIC_REST_URL_PREFIX`      | No       | `/wp-json`            | The WordPress REST API URL prefix.                                                                                                                                                               | `restUrlPrefix`            |
+| `NEXT_PUBLIC_WP_UPLOADS_DIRECTORY` | No       | `/wp-content/uploads` | The relative path to the WordPress uploads directory.                                                                                                                                            | `uploadsDirectory`         |
+| `NEXT_PUBLIC_CORS_PROXY_PREFIX`    | No       |                       | The prefix for the CORS proxy. If unset, no proxy will be used.                                                                                                                                  | `corsProxyPrefix`          |
+| `INTROSPECTION_TOKEN`              | Yes      |                       | Token used for authenticating GraphQL introspection queries with GraphQL Codegen.                                                                                                                | N/A                        |
 
 Additionally, if you are running a local development environment without a valid SSL certificate, you can set the following environment variable:
 
@@ -82,5 +82,5 @@ You can access the configuration values in your application code using the `getC
 import { getConfig } from '@snapwp/core/config';
 
 // Or any other valid configuration property.
-const { nextUrl, homeUrl, parserOptions } = getConfig();
+const { frontendUrl, wpHomeUrl, parserOptions } = getConfig();
 ```
diff --git a/docs/cors.md b/docs/cors.md
@@ -62,25 +62,8 @@ To further mitigate CORS issues, SnapWP includes a CORS middleware that proxies
 
 ### Enabling the CORS Middleware
 
-To enable the CORS proxy feature, update your `snapwp.config.mjs` file:
+To enable the CORS proxy feature, update your `.env` file:
 
-```javascript
-/** @type {import('@snapwp/core/config').SnapWPConfig} */
-const config = {
-	// Other configuration options
-	useCorsProxy: true,
-};
-
-export default config;
-```
-
-### Customizing the Proxy Prefix
-
-By default, the proxy prefix is set to `/proxy`. If needed, you can override this by specifying `corsProxyPrefix` in the configuration.
-
-```javascript
-const config = {
-	useCorsProxy: process.env.NODE_ENV !== 'production', // Enable CORS proxy in nonproduction environments.
-	corsProxyPrefix: '/custom-proxy', // Optional custom prefix
-};
+```dotenv
+NEXT_PUBLIC_CORS_PROXY_PREFIX={prefix-value}
 ```
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -70,7 +70,7 @@ To create a new headless WordPress app using SnapWP, follow these steps:
     1. Navigate to the newly created app.
     2. Run `npm install`.
     3. Run `npm run dev` (for development) or `npm run build && npm run start` (for production)
-    4. Visit the `NEXT_PUBLIC_URL` from `.env` (updated in Step 2), in your browser to see SnapWP in action!
+    4. Visit the `NEXT_PUBLIC_FRONTEND_URL` from `.env` (updated in Step 2), in your browser to see SnapWP in action!
 
 ### Manual Installation
 

diff --git a/examples/nextjs/starter/.env.example b/examples/nextjs/starter/.env.example
@@ -1,20 +1,27 @@
-# Enable if connecting to a self-signed cert
-# NODE_TLS_REJECT_UNAUTHORIZED="0"
+# Enable if connecting to a self-signed cert.
+# NODE_TLS_REJECT_UNAUTHORIZED=0
 
-# The headless frontend domain URL
-NEXT_PUBLIC_URL="http://localhost:3000"
+# The URL of the Next.js "headless" frontend.
+NEXT_PUBLIC_FRONTEND_URL=http://localhost:3000
 
-# The WordPress "frontend" domain URL
-NEXT_PUBLIC_WORDPRESS_URL="http://localhost"
+# The traditional WordPress frontend domain URL. E.g. https://my-headless-site.local
+NEXT_PUBLIC_WP_HOME_URL=
 
-# The WordPress GraphQL endpoint
-NEXT_PUBLIC_GRAPHQL_ENDPOINT="graphql"
+# The backend "WordPress Address" URL where your WordPress core files reside.
+# Only needed if different than `NEXT_PUBLIC_WP_HOME_URL`. E.g. https://my-headless-site.local/wp/
+# NEXT_PUBLIC_WP_SITE_URL=
 
-# The WordPress Uploads directory path
-# NEXT_PUBLIC_WORDPRESS_UPLOADS_PATH=/wp-content/uploads
+# The WordPress GraphQL endpoint.
+NEXT_PUBLIC_GRAPHQL_ENDPOINT=graphql
 
-# The WordPress REST URL Prefix
-# NEXT_PUBLIC_WORDPRESS_REST_URL_PREFIX=/wp-json
+# The WordPress REST API URL prefix.
+# NEXT_PUBLIC_REST_URL_PREFIX=/wp-json
 
-# Token used for authenticating GraphQL introspection queries
+# The relative path to the WordPress uploads directory.
+# NEXT_PUBLIC_WP_UPLOADS_DIRECTORY=/wp-content/uploads
+
+# The CORS proxy prefix to use when bypassing CORS restrictions from WordPress server. If unset, no proxy will be used.
+# NEXT_PUBLIC_CORS_PROXY_PREFIX=/proxy
+
+# Token used for authenticating GraphQL introspection queries.
 INTROSPECTION_TOKEN=
diff --git a/examples/nextjs/starter/codegen.ts b/examples/nextjs/starter/codegen.ts
@@ -14,7 +14,7 @@ const config: CodegenConfig = {
 	schema: process.env.GRAPHQL_SCHEMA_FILE ?? [
 		{
 			[ generateGraphqlUrl(
-				process.env.NEXT_PUBLIC_WORDPRESS_URL,
+				process.env.NEXT_PUBLIC_WP_HOME_URL,
 				process.env.NEXT_PUBLIC_GRAPHQL_ENDPOINT
 			) ]: {
 				headers: {

diff --git a/packages/blocks/jest.setup.js b/packages/blocks/jest.setup.js
@@ -4,17 +4,18 @@ import 'isomorphic-fetch';
 global.__snapWPConfig = {};
 
 global.__envConfig = {
-	nextUrl: 'https://env-next.example.com',
-	homeUrl: 'https://env-home.example.com',
+	frontendUrl: 'https://env-next.example.com',
+	wpHomeUrl: 'https://env-home.example.com',
+	wpSiteUrl: 'https://env-home.example.com',
 	graphqlEndpoint: 'env-index.php?graphql',
 	uploadsDirectory: '/env-wp-content/uploads',
 	restUrlPrefix: '/env-wp-json',
 };
 
-process.env.NEXT_PUBLIC_URL = global.__envConfig.nextUrl;
-process.env.NEXT_PUBLIC_WORDPRESS_URL = global.__envConfig.homeUrl;
+process.env.NEXT_PUBLIC_FRONTEND_URL = global.__envConfig.frontendUrl;
+process.env.NEXT_PUBLIC_WP_HOME_URL = global.__envConfig.wpHomeUrl;
+process.env.NEXT_PUBLIC_WP_SITE_URL = global.__envConfig.wpSiteUrl;
 process.env.NEXT_PUBLIC_GRAPHQL_ENDPOINT = global.__envConfig.graphqlEndpoint;
-process.env.NEXT_PUBLIC_WORDPRESS_UPLOADS_PATH =
+process.env.NEXT_PUBLIC_WP_UPLOADS_DIRECTORY =
 	global.__envConfig.uploadsDirectory;
-process.env.NEXT_PUBLIC_WORDPRESS_REST_URL_PREFIX =
-	global.__envConfig.restUrlPrefix;
+process.env.NEXT_PUBLIC_REST_URL_PREFIX = global.__envConfig.restUrlPrefix;