feat: robust handling for internal uri

.changeset/eleven-experts-feel.md

@@ -0,0 +1,10 @@
+---
+"@snapwp/blocks": minor
+"@snapwp/query": minor
+"@snapwp/types": minor
+"@snapwp/core": minor
+"@snapwp/next": minor
+"snapwp": minor
+---
+
+Update WordPress and internal URI handling, and add a robust URI updater between WP and Next, and vice versa.

.env.example

@@ -1,20 +1,25 @@
 # 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
+# Token used for authenticating GraphQL introspection queries
+INTROSPECTION_TOKEN=
+
+# The CORS proxy prefix to use when bypassing CORS restrictions from WordPress server, Possible values: string|false Default: /proxy, This means for script module next app will make request NEXT_PUBLIC_FRONTEND_URL/proxy/{module-path}
+# NEXT_PUBLIC_CORS_PROXY_PREFIX=/proxy
 
-# The WordPress "frontend" domain URL
-NEXT_PUBLIC_WORDPRESS_URL=https://headless-demo.local
+# The headless frontend domain URL
+NEXT_PUBLIC_FRONTEND_URL=http://localhost:3000
 
 # 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 URL Prefix
-# NEXT_PUBLIC_WORDPRESS_REST_URL_PREFIX=/wp-json
+# NEXT_PUBLIC_REST_URL_PREFIX=/wp-json
 
-# Token used for authenticating GraphQL introspection queries
-INTROSPECTION_TOKEN=
+# The WordPress "frontend" domain URL e.g. https://my-headless-site.local
+NEXT_PUBLIC_WP_HOME_URL=
+
+# NEXT_PUBLIC_WP_SITE_URL=
+
+# The WordPress Uploads directory path
+# NEXT_PUBLIC_WP_UPLOADS_DIRECTORY=/wp-content/uploads

docs/config-api.md

@@ -2,8 +2,8 @@
 
 To ensure consistency and enable composability across the SnapWP framework, we use a shared configuration API that unifies two source:
 
--   The environment variables in the `.env` file.
--   The `snapwp.config.ts` config.
+- The environment variables in the `.env` file.
+- The `snapwp.config.ts` config.
 
 Configurations are used to power behavior behind the scenes, but can also be used directly in your application code with the `getConfig` function.
 
@@ -15,16 +15,15 @@ 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 site.                                                      | `frontendUrl`              |
+| `NEXT_PUBLIC_WP_HOME_URL`          | Yes      |                       | The WordPress frontend domain URL.                                                | `wpHomeUrl`                |
+| `NEXT_PUBLIC_WP_SITE_URL`          | Yes      |                       | The WordPress site URL.                                                           | `wpSiteUrl`                |
+| `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_WP_UPLOADS_DIRECTORY` | No       | `/wp-content/uploads` | The relative path to the WordPress uploads directory.                             | `uploadsDirectory`         |
+| `NEXT_PUBLIC_REST_URL_PREFIX`      | No       | `/wp-json`            | The WordPress REST API URL prefix.                                                | `restUrlPrefix`            |
 
 Additionally, if you are running a local development environment without a valid SSL certificate, you can set the following environment variable:
 
@@ -65,11 +64,11 @@ Config values are available via their respective keys in the `getConfig()` funct
 SnapWP extends the Next.js configuration using the `withSnapWP` function to configure certain settings automatically based on your Config API, such as using the WordPress URL for [`images.remotePatterns`](https://nextjs.org/docs/app/api-reference/components/image#remotepatterns).
 
 ```ts
-import withSnapWP from '@snapwp/next/withSnapWP';
+import withSnapWP from "@snapwp/next/withSnapWP";
 
-export default await withSnapWP( {
-	// Your Next.js configuration
-} );
+export default await withSnapWP({
+  // Your Next.js configuration
+});
 ```
 
 This function automatically loads configurations from `.env` and `snapwp.config.js|mjs|ts`, making them available for your Next.js application.
@@ -79,8 +78,8 @@ This function automatically loads configurations from `.env` and `snapwp.config.
 You can access the configuration values in your application code using the `getConfig` function from `@snapwp/config`.
 
 ```ts
-import { getConfig } from '@snapwp/core/config';
+import { getConfig } from "@snapwp/core/config";
 
 // Or any other valid configuration property.
-const { nextUrl, homeUrl, parserOptions } = getConfig();
+const { frontendUrl, wpHomeUrl, parserOptions } = getConfig();
 ```

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}
 ```

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
 

examples/nextjs/starter/.env.example

@@ -1,20 +1,26 @@
 # Enable if connecting to a self-signed cert
-# NODE_TLS_REJECT_UNAUTHORIZED="0"
+# NODE_TLS_REJECT_UNAUTHORIZED=0
 
-# The headless frontend domain URL
-NEXT_PUBLIC_URL="http://localhost:3000"
+# Token used for authenticating GraphQL introspection queries
+INTROSPECTION_TOKEN=
 
-# The WordPress "frontend" domain URL
-NEXT_PUBLIC_WORDPRESS_URL="http://localhost"
+# The CORS proxy prefix to use when bypassing CORS restrictions from WordPress server, Possible values: string|false Default: /proxy, This means for script module next app will make request NEXT_PUBLIC_FRONTEND_URL/proxy/{module-path}
+# NEXT_PUBLIC_CORS_PROXY_PREFIX=/proxy
 
-# The WordPress GraphQL endpoint
-NEXT_PUBLIC_GRAPHQL_ENDPOINT="graphql"
+# The headless frontend domain URL
+NEXT_PUBLIC_FRONTEND_URL=http://localhost:3000
 
-# 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
+# NEXT_PUBLIC_REST_URL_PREFIX=/wp-json
 
-# Token used for authenticating GraphQL introspection queries
-INTROSPECTION_TOKEN=
+# The WordPress "frontend" domain URL e.g. https://my-headless-site.local
+NEXT_PUBLIC_WP_HOME_URL=
+
+# The WordPress "backend" Site Address. Uncomment 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_WP_UPLOADS_DIRECTORY=/wp-content/uploads

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: {

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;

packages/blocks/src/blocks/core-button.tsx

@@ -1,11 +1,10 @@
-import type { ButtonHTMLAttributes } from 'react';
-import { cn, getStylesFromAttributes, replaceHostUrl } from '@snapwp/core';
-import { getConfig } from '@snapwp/core/config';
+import { cn, getStylesFromAttributes } from '@snapwp/core';
 import { Link, Parse } from '@snapwp/next';
 import type {
 	CoreButton as CoreButtonType,
 	CoreButtonProps,
 } from '@snapwp/types';
+import type { ButtonHTMLAttributes } from 'react';
 
 /**
  * Renders the core/button block.
@@ -32,7 +31,6 @@ const CoreButton: CoreButtonType = ( { attributes }: CoreButtonProps ) => {
 	const classNames = cn( cssClassName );
 	const styleObject = getStylesFromAttributes( { style } );
 
-	const { homeUrl, nextUrl } = getConfig();
 	const commonProps = {
 		className: linkClassName ?? undefined,
 		style: styleObject,
@@ -55,11 +53,11 @@ const CoreButton: CoreButtonType = ( { attributes }: CoreButtonProps ) => {
 	}
 
 	if ( url ) {
-		const href = replaceHostUrl( url, homeUrl, nextUrl );
+		// No need to convert URL to internal URL as the Link component handles it.
 		return (
 			<div className={ classNames }>
 				<Link
-					href={ href }
+					href={ url }
 					target={ linkTarget ?? undefined }
 					rel={ rel ?? undefined }
 					{ ...commonProps }

packages/blocks/src/blocks/tests/__snapshots__/core-button.test.tsx.snap

@@ -81,7 +81,7 @@ exports[`CoreButton Component renders with corrected url 1`] = `
   >
     <a
       class="link-class"
-      href="https://env-next.example.com/sub"
+      href="/sub"
       rel="noopener"
       style="color: red;"
       target="_blank"

packages/blocks/src/blocks/tests/core-button.test.tsx

@@ -60,14 +60,14 @@ describe( 'CoreButton Component', () => {
 	} );
 
 	test( 'renders with corrected url', () => {
-		const { homeUrl, nextUrl } = getConfig();
+		const { wpHomeUrl } = getConfig();
 		const exampleAttributes = {
 			cssClassName: 'test-class',
 			linkClassName: 'link-class',
 			style: JSON.stringify( { color: 'red' } ),
 			text: 'Click Me',
 			title: 'Test Button',
-			url: homeUrl + '/sub',
+			url: wpHomeUrl + '/sub',
 			tagName: 'a',
 			rel: 'noopener',
 			linkTarget: '_blank',
@@ -79,7 +79,7 @@ describe( 'CoreButton Component', () => {
 		);
 		const linkElement = screen.getByRole( 'link', { name: 'Click Me' } );
 
-		expect( linkElement ).toHaveAttribute( 'href', nextUrl + '/sub' );
+		expect( linkElement ).toHaveAttribute( 'href', '/sub' );
 		expect( asFragment() ).toMatchSnapshot();
 	} );
 

packages/cli/CHANGELOG.md

@@ -4,50 +4,50 @@
 
 ### Patch Changes
 
-- [#116](https://github.com/rtCamp/snapwp/pull/116) [`e7d4a56`](https://github.com/rtCamp/snapwp/commit/e7d4a56b1a6cf230bca87a25a4ac25b69180cabe) Thanks [@Pathan-Amaankhan](https://github.com/Pathan-Amaankhan)! - chore: Apply and enforce ESLint rules to `bin` and `cli` files
+-   [#116](https://github.com/rtCamp/snapwp/pull/116) [`e7d4a56`](https://github.com/rtCamp/snapwp/commit/e7d4a56b1a6cf230bca87a25a4ac25b69180cabe) Thanks [@Pathan-Amaankhan](https://github.com/Pathan-Amaankhan)! - chore: Apply and enforce ESLint rules to `bin` and `cli` files
 
 ## 0.1.1
 
 ### Patch Changes
 
-- [#109](https://github.com/rtCamp/snapwp/pull/109) [`e31540c`](https://github.com/rtCamp/snapwp/commit/e31540cb97091eca81f02d824b4c58eb9fa71f5e) Thanks [@ashutoshgautams](https://github.com/ashutoshgautams)! - docs: Add directory structure `examples/nextjs/starter` readme.
+-   [#109](https://github.com/rtCamp/snapwp/pull/109) [`e31540c`](https://github.com/rtCamp/snapwp/commit/e31540cb97091eca81f02d824b4c58eb9fa71f5e) Thanks [@ashutoshgautams](https://github.com/ashutoshgautams)! - docs: Add directory structure `examples/nextjs/starter` readme.
 
 ## 0.1.0
 
 ### Minor Changes
 
-- [#81](https://github.com/rtCamp/snapwp/pull/81) [`2595e37`](https://github.com/rtCamp/snapwp/commit/2595e376efb9a24b9caa0be9146976ec1386ffc4) Thanks [@justlevine](https://github.com/justlevine)! - chore: SemVer bump to 0.1.0
+-   [#81](https://github.com/rtCamp/snapwp/pull/81) [`2595e37`](https://github.com/rtCamp/snapwp/commit/2595e376efb9a24b9caa0be9146976ec1386ffc4) Thanks [@justlevine](https://github.com/justlevine)! - chore: SemVer bump to 0.1.0
 
 ### Patch Changes
 
-- [#77](https://github.com/rtCamp/snapwp/pull/77) [`a3c3f6b`](https://github.com/rtCamp/snapwp/commit/a3c3f6b27994b1c5fee555e23c4ea40f7b88667a) Thanks [@SH4LIN](https://github.com/SH4LIN)! - feat: Improve handling of GraphQL errors and the Error Boundary UI.
+-   [#77](https://github.com/rtCamp/snapwp/pull/77) [`a3c3f6b`](https://github.com/rtCamp/snapwp/commit/a3c3f6b27994b1c5fee555e23c4ea40f7b88667a) Thanks [@SH4LIN](https://github.com/SH4LIN)! - feat: Improve handling of GraphQL errors and the Error Boundary UI.
 
-- [#80](https://github.com/rtCamp/snapwp/pull/80) [`777305f`](https://github.com/rtCamp/snapwp/commit/777305fcfe0ac104fc0259f81a1ec93451e14b50) Thanks [@justlevine](https://github.com/justlevine)! - chore: Update `snapwp` package readme
+-   [#80](https://github.com/rtCamp/snapwp/pull/80) [`777305f`](https://github.com/rtCamp/snapwp/commit/777305fcfe0ac104fc0259f81a1ec93451e14b50) Thanks [@justlevine](https://github.com/justlevine)! - chore: Update `snapwp` package readme
 
-- [#76](https://github.com/rtCamp/snapwp/pull/76) [`4ded470`](https://github.com/rtCamp/snapwp/commit/4ded47012041099e01c8231cfa367c389de10171) Thanks [@justlevine](https://github.com/justlevine)! - chore: remove the NextJS example's package-lock.json from VCS.
+-   [#76](https://github.com/rtCamp/snapwp/pull/76) [`4ded470`](https://github.com/rtCamp/snapwp/commit/4ded47012041099e01c8231cfa367c389de10171) Thanks [@justlevine](https://github.com/justlevine)! - chore: remove the NextJS example's package-lock.json from VCS.
 
 ## 0.0.6
 
 ### Patch Changes
 
-- docs: Update, backfill, and cleanup readmes
-- chore: Cleanup tsconfig rulesets and remediate unearthed issues
+-   docs: Update, backfill, and cleanup readmes
+-   chore: Cleanup tsconfig rulesets and remediate unearthed issues
 
 ## 0.0.4 - 2025-02-07
 
-- fix: improve cross-platform compatibility for the `snapwp` command
+-   fix: improve cross-platform compatibility for the `snapwp` command
 
 ## 0.0.3 - 2025-02-03
 
-- fix: update regex in `snapwp` command to avoid `node_modules`
-- chore: add missing namespace proxies to Verdaccio config
+-   fix: update regex in `snapwp` command to avoid `node_modules`
+-   chore: add missing namespace proxies to Verdaccio config
 
 ## 0.0.2 - 2025-01-31
 
-- fix: remove internal `npm install` command to prevent dependency conflicts with the script.
-- docs: add local README.md to the package
-- docs: fix references to `npx snapwp`
+-   fix: remove internal `npm install` command to prevent dependency conflicts with the script.
+-   docs: add local README.md to the package
+-   docs: fix references to `npx snapwp`
 
 ## 0.0.1 - 2025-01-30
 
-- Initial (public) release.
+-   Initial (public) release.

packages/cli/README.md

@@ -56,7 +56,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!
 
 ## Contributing
 

packages/core/README.md

@@ -27,7 +27,7 @@ const classNames = findElementAndGetClassNames( renderedHTML, '#div-2' ); // cla
 ```javascript
 import { generateGraphqlUrl } from '@snapwp/core';
 
-const url = generateGraphqlUrl( homeUrl, graphqlEndpoint );
+const url = generateGraphqlUrl( wpHomeUrl, graphqlEndpoint );
 ```
 
 ```javascript