Blueprints: Isomorphic DOM - DOMParser, FormData, fetch

[eliot-akira]

From this merged pull request:

• Isomorphic PHP, Isomorphic Blueprints #214

@wp-playground/blueprints will need to be smart about providing a Node.js polyfill for new DOMParser() and fetch().

Currently, the following browser globals are found in the blueprints package.

• DOMParser

  wordpress-playground/packages/playground/blueprints/src/lib/steps/common.ts

  Line 4 in a38fa9a

  return new DOMParser().parseFromString(response.text, 'text/html')!;

  Used in:
  • blueprints/src/lib/steps/install-theme.ts‎
  • blueprints/src/lib/steps/install-plugin.ts‎
• FormData

  • wordpress-playground/packages/playground/blueprints/src/lib/steps/install-theme.ts

    Lines 75 to 77 in a38fa9a

    	const themeFormData = new FormData(
    	themeFormPage.querySelector('.wp-upload-form')! as HTMLFormElement
    	) as any;

  • wordpress-playground/packages/playground/blueprints/src/lib/steps/install-plugin.ts

    Lines 72 to 74 in a38fa9a

    	const pluginFormData = new FormData(
    	pluginFormPage.querySelector('.wp-upload-form')! as HTMLFormElement
    	) as any;

• fetch

  wordpress-playground/packages/playground/blueprints/src/lib/resources.ts

  Line 215 in a38fa9a

  let response = await fetch(url);

---

Possible solution: Prepare a proxy module/package that exports native DOM API for the browser and jsdom for Node.js.

The closest NPM package I found was k0michi/isomorphic-dom, which uses the exports property in its package.json to define browser and server exports.

There's also fetch-shim which does the same for fetch and undici; however, this latter module is now in Node.js core as global fetch since v18 so it's no longer necessary. EDIT: Just learned that global FormData is also available since Node.js v18. So it's only DOMParser that needs to be polyfilled on the server side.

[adamziel]

Thank you, this would be great!

An alternative fix would be to remove reliance on DOMParser entirely, like what this PR did for the activatePlugin step: https://github.com/WordPress/wordpress-playground/pull/351/files

[eliot-akira]

OK, I see there are two diverging paths, depending on the long-term design of Playground Blueprints.

• Remove use of asDOM helper, DOMParser, and any browser-specific DOM API (and types like HTMLFormElement)

  This implies that Blueprint steps, existing and those added in the future, should avoid DOM manipulations to perform their actions. That might be limiting, but the advantage is that the steps can run on browser and server side by only using available Playground API.

  I'm kind of leaning toward this approach, it seems simpler to maintain. If you agree, I can start on a pull request to attempt a rewrite of the installPlugin and installTheme steps.

• Provide an isomorphic DOM library that exports native DOM API for the browser and jsdom for Node.js

  This way, Blueprint steps can perform DOM manipulations through this proxy library. They should take care to avoid using any other browser-specific API beyond what jsdom and Node.js provides. The advantage is more flexibility for future steps to be added - maybe there are certain steps that can only be accomplished via the DOM. The disadvantage is the complexity of pretending that there's a DOM on the server side, and possible inefficiency of jsdom library.

  I found in the PR you mentioned that there's a commit which modified the asDOM helper to dynamically import jsdom on the server side. ed28a2b#diff-2c904654899ecec0c61cfd1da4e48ed08c13010af043f16185cedb8e68b9f37dR3-R9

  In packages/playground/blueprints/src/lib/steps/common.ts

  export async function asDOM(response: PHPResponse) {
  	if (typeof process !== 'undefined' && process.release?.name === 'node') {
  		const { JSDOM } = await import('jsdom');
  		return new JSDOM(response.text).window.document;
  	} else {
  		return new DOMParser().parseFromString(response.text, 'text/html')!;
  	}
  }

  In packages/playground/client/vite.config.ts

  	rollupOptions: {
  		// External packages that should not be bundled into your library.
  		external: ['jsdom'],
  	},

  The simplest solution might be to bring back the above changes, then the installPlugin and installTheme steps would work as is on the server. And future steps could use the asDOM helper for any DOM manipulations.

  I briefly looked into creating a new package using nx generate, something like @wp-playground/isomorphic-dom. It seems quite involved, like figuring out how to provide separate exports for browser and server. I also question whether this is even necessary, if the DOM proxy would only be used in the blueprints package.

[adamziel]

I'm kind of leaning toward this approach, it seems simpler to maintain. If you agree, I can start on a pull request to attempt a rewrite of the installPlugin and installTheme steps.

Yes please @eliot-akira ! That sounds absolutely fantastic 💯

I briefly looked into creating a new package using nx generate, something like @wp-playground/isomorphic-dom. It seems quite involved, like figuring out how to provide separate exports for browser and server. I also question whether this is even necessary, if the DOM proxy would only be used in the blueprints package.

That's also my concern with isomorphic DOM. If Playground had some public API that exposed DOM functions that would be different, but right now DOM is an implementation detail and a burden to maintain.

DOM might become indispensable one day, and if it does we'll figure it out based on the specific use-case that comes up. For now, I really like the idea of avoiding the complexity associated with a custom isomorphic-dom package.

[eliot-akira]

Hi @sejas - I wanted to mention this issue concerning the use of DOMParser in Blueprint steps. I think it's related to the question of supporting all Blueprint steps in Node.js (and wp-now), and also about supporting Node.js version 18 which lacks the File and CustomEvent class.

• Blueprints: add support for NodeJS #576
• Blueprints and Client: update engine to node v20 on package.json #591
• wp-now: Restore node 18 support playground-tools#87

---

The original topic of this issue was about "isomorphic DOM", using the jsdom library to polyfill DOMParser and other browser-specific classes, so that Blueprints can run on Node.js.

With Adam's feedback, the approach was changed to remove the use of all browser-only APIs in Blueprint steps.

Mainly that involved rewriting some steps to not use GET/POST request and DOMParser for interacting with the site, and instead call PHP functions directly to achieve the same result.

Apparently that was done for activatePlugin and activateTheme already, and I worked on a pull request for rewriting installPlugin and installTheme.

• wp now: activate plugin and theme the first time #351
• Remove DOMParser from Blueprints: installPlugin and installTheme #427

The remaining step that's yet to be rewritten is importFile.

---

While I was working on the PR, I discovered that jsdom has an incomplete polyfill for the File class, which is missing the method arrayBuffer(). That caused some tests to fail, so I had to wrap the class to provide the method.

• Polyfill the File class in JSDOM which lacks arrayBuffer() method

This workaround requires that all Blueprint steps that use the File class must import it from steps/common, instead of assuming that it exists as a global name. That may be convenient for polyfilling the same class for Node.js 18.

---

Also relevant:

• Blueprints API: Isomorphism in the documentation
• Isomorphic PHP, Isomorphic Blueprints #214

[adamziel]

The only step still using the DOM API is importFile. The arrayBuffer() method and File and Blob logic have been polyfilled in Node.js.