Sitecore 10.4.0 form in headless JSS react app

Recently, in Sitecore Slack channel, I came across a scenario which seemed more like an issue caused due to oversight but wasn't the case when I myself delved into it. This blog post is about providing a consolidated update based on scattered resources: in the web, discussion with Sitecore support. While I've provided the details in this post, I cover the setup process also in this post. I've used Sitecore 10.4 Form in a Headless Services 22.0.11 setup. 

The concerned error message(s) are:

XPE Error:

"Page: No renderer for form element type {D819B43E-C136-4392-9393-8BE7FCE32F5E}"

Form Submit Error:

Unexpected token '<', "<!DOCTYPE "... is not valid JSON

To get to the error(s) and provide the context, I decided to setup the Sitecore instance with the concerned Sitecore Headless Service. So, here is the step-by-step process/analysis based on Sitecore React documentation. Note that screen shots were picked from different executions so, domain names could differ.

Process/Command overview:

Pre-requisites:

a. Install Sitecore 10.4.0

b. Install Headless Services 22.0.11 package in the Sitecore 10.4.0 instance

c. Ensure SC API key is created under /sitecore/system/Settings/Services/API Keys:

d. In case if you wish to create a separate https binding, here is the script but existing https binding created for the site is enough. 

PS Script for https shenanigans:

########

#######

Ensure to check if the IIS https binding points to correct certificate after running the above script else ensure to select the same!

Steps:

1. Now, setup react app in a new folder by executing npx create-sitecore-jss react and make the following selections:

2. Time to setup jss app so, execute the jss command(s) from the sub-directory where package.json is present -

For a neater approach, cd react folder and execute jss setup followed by,

jss deploy config

While executing the above deploy config command, you might get error-3 and the resolution is to run PowerShell in admin mode before executing the command!

The above command(s) create the scssconfig.json and the inputs for the same look like follows:

Note: the above screen shot shows http binding but cms site https domain can be used. The main difference between using http and https urls is the need to pass the certificate thumbprint in case of https for the highlighted commands here below in the post.

3. Next, execute the following command to build and deploy the jss app to the dist folder under web root: 

jss deploy app -c -d

On the other hand, if using https binding, you need to:

a. Get certificate thumbprint:

#####

#####

You could also copy-over the thumbprint from site binding:

b. Execute  jss deploy app -c -d --acceptCertificate <cert thumbprint>

If you get the following error, ensure to add an entry for the https binding in the hosts file and re-execute the command.

======

Unexpected response from import service:

getaddrinfo ENOTFOUND sc104rjsnewinstscapp.dev.local

======

On the other hand, if you get the following error, probably the headless package isn't installed in the Sitecore instance among other possibilities mentioned here. So, install the same and re-execute the command.

======

Sending package sitecore\package\sitecore-jss-app.1745250314109.manifest.zip to https://sc104rjsnewinstscapp.dev.local/sitecore/api/jss/import...

Unexpected response from import service:

Status message: Found

Status: 302

======

Desired end-result:

From hereon, whenever there are changes made to client-side code, the above command or a deployment related command like jss deploy files needs to be executed to effect the jss changes onto the site.

Sitecore JSS App End-result:

4. Now, go to Forms from Desktop and create a blank form with submit button, add save data as a bare minimal and name the form as need-be, this form is anyway de-coupled and will be selected as a datasource in the coming steps.

5. If the form is not visible on save, go to control panel > Indexing manager and rebuild master index

6. Now, execute jss deploy component SitecoreForm --allowedPlaceholders jss-main in the client folder. This step creates an item named SitecoreForm under /sitecore/layout/Renderings/Project/sitecore-jss-app 

If using https binding, the above command should be:

 jss deploy component SitecoreForm --allowedPlaceholders jss-main --acceptCertificate <cert thumbprint>

Else if you execute without the --acceptCertificate / cert thumbprint, you will get the following error in the cmd prompt:

======

Unexpected response from import service:

self-signed certificate

C:\projects\sc104rjsint\react\node_modules\@sitecore-jss\sitecore-jss-cli\dist\cjs\cli-shared.js:20

    throw err;

    ^

undefined

(Use `node --trace-uncaught ...` to show where the exception was thrown)

Node.js v18.18.1

======

Now, in Sitecore, for the created rendering item, set the following fields:

Datasource Location: /sitecore/Forms

Datasource Template: /sitecore/templates/System/Forms/Form

Rendering Contents Resolver: Sitecore Forms Resolver

At this point, if you open the home page in XPE, you would get the amber message in XPE that the form doesn't have react implementation. 

"JSS component is missing react implementation. See the developer console for more information."

The inference is, above item needs a couple of local js files aka scaffoldings. 

7. So, execute jss scaffold SitecoreForm to see the SitecoreForm.js  file created in client-side as follows:

Note that the above command creates two entries in the file system: 

sitecore\definitions\components\SitecoreForm.sitecore.js

src\components\SitecoreForm.js

So, if you want to recreate the js files, ensure to delete and rerun the command.

8. Since the scaffold-ed file doesn't have a form placeholder, in order to render the controls from Sitecore Forms, replace the concerned js file with the following file.

Prerequisite: for the following SitecoreForm.js file to compile fine, as per documentation, first execute 

npm install @sitecore-jss/sitecore-jss-forms @sitecore-jss/sitecore-jss-react-forms

######

######

Now, execute jss deploy files to deploy the build to the web root dist folder:

Note that if you're trying to setup a nextjs app, ironically, jss deploy files command wouldn't work and it would be good to look at this blog post by Sitecore MVP Sandeep Pote.

9. Now, on a headless page and in my case to the jssmain placeholder, add the SitecoreForm rendering or if you already added the component and saved it as part of earlier steps, just refresh the XPE:

10. Set the datasource for the above rendering to the form created in step 4

11. In the XPE, once the rendering is added, if the rendering doesn't have the Form tag, it would look like this with the basic scaffolded code:

On the other hand, it will display Error-2 if using a form tag, which is the context of this blog post.

12. Parking that error aside, if you installed an earlier version of headless, the expected behaviour is - once you save the form, preferably publish the form as well as the site, and execute jss start:connected on the client-side, you will be able to see the form in browser running from localhost:3000 but in the command prompt you might see the following errors:

=========

[HPM] Error occurred while proxying request localhost:3000/layouts/system/VisitorIdentificationCSS.aspx?tstamp=1745227791993 to https://sc104rjsinstscapp.dev.local/ [DEPTH_ZERO_SELF_SIGNED_CERT] (https://nodejs.org/api/errors.html#errors_common_system_errors)

=========

I  decided to ignore the messages since they seemed relevant to the context or in other words, it alludes to the fact that the certificate isn't created by a trusted third-party, at least that is what i understood from this definition - 

Note: Always open localhost:3000 incognito mode to bust any cache as well as network errors

Also, note that I didn't modify any other file like setupProxy.js or set the sitecoreApiHost in SitecoreForm.js component to '' as mentioned in the documentation since it seemed more relevant to NextJS. I also didn't apply any patch as mentioned here understandably since the article is relevant for Headless 20.0.0 while I installed a version above 20.0.0.

Submit action:

So, I then went ahead and submitted the data from the form and I could see the result in the exported data:

P.S. The above form submission was done on Sitecore 10.4 and Sitecore Headless Services Server XP 21.0.583 since in case of 22.0.11, I had issues in XPE due to Error-2 as mentioned below. I saw a SO post about a hotfix that worked fine for Headless 22.0.11 but I didn't have much luck with it. So, contacted Sitecore support and was advised to unzip the downloaded hotfix file, install the zip package present at the same level as the readme.txt and that worked fine. Also, note that I used https binding all through my process working with Sitecore Headless Services Server for XP since secured connection is mentioned as a prerequisite for Sitecore Forms.

Network tab for successful form submission:

On the other hand, in the latest version as well as older versions as far as v21.0.583 or v21.0.587, if I passed '' instead of sitecoreApiHost in the SitecoreForm.js (as stated in the Sitecore React documentation), deployed the files, started the jss app and submitted form data, I received the following JSON error. The Sitecore error log didn't have any detailed errors. From the screen shot, it is evident that the application is checking for an api in client-side resulting in 404 error instead of invoking the server since api host has been sent as blank in this case. I reached out to Sitecore support regarding the same and then understood that the passing '' comment in the documentation is not for connected mode but for headless ssr proxy mode. 

Unexpected token '<', "<!DOCTYPE "... is not valid JSON

So, at this point, you probably know the cause for the above 404 error and the resolution is obviously to NOT pass '' but the actual sitecoreApiHost value in connected mode! Note that even if you apply the patch mentioned here, which is irrelevant to this scenario, the error would continue to occur on form submit since the call hasn't made it to the server and that error html is what gets displayed.

Command ready-reckoner:

Command	Details
npx create-sitecore-jss react	Local react Setup
jss setup	Setup jss app and a cleaner approach instead of directly running jss deploy config
jss deploy config	Setup configs and copies over automatically if this command is run after jss setup
jss deploy app -c -d	Deploy App
jss deploy component <name> --allowedPlaceholders <phname>	Deploy component item
Jss scaffold <name>	Create component js files
jss deploy files	Deploy js files

Errors/Resolutions:

Error-1:

You receive the following error due to the absence of http binding for the site while trying to deploy jss app to Sitecore web root:

Sending package sitecore\package\sitecore-jss-app.1744591818613.manifest.zip to https://sc104headlesssc.dev.local/sitecore/api/jss/import...

Unexpected response from import service:

unable to verify the first certificate

Resolution:

Input the http-based site url (added as part of site bindings), or the default https binding url, during jss setup process. Now, once you execute jss deploy app -c -d (with --acceptCertificate for https),  deployUrl will point to the http-based or https-based hostname and the deployment will be successful.

Error-2:

In XPE, once you add the component, you will encounter this error:

Page: No renderer for form element type {D819B43E-C136-4392-9393-8BE7FCE32F5E}

Resolution:

The reason for the above error is, Headless Services 22.0.11 isn't compatible with the Form tag in your scaffolded .js file. The root cause is a change in Sitecore.JavaScriptServices.Forms.dll  as part of Headless Services 22.0.11. You can install the hotfix (but ensure to unzip and install the zip at the same level as the readme.txt). Note that in case of lower versions of Headless Services like v21.0.583 or v21.0.587, this error doesn't occur. 

Error-3:

Error: EPERM: operation not permitted, mkdir 'C:\inetpub\wwwroot\sc104nextjsnewinstsc.dev.local\App_Config\Include\zzz'

    at Object.mkdirSync (node:fs:1398:3)

    at module.exports.makeDirSync (C:\projects\sc104nextjsnewinst\nextjs\node_modules\fs-extra\lib\mkdirs\make-dir.js:23:13)

    at deploy (C:\projects\sc104nextjsnewinst\nextjs\node_modules\@sitecore-jss\sitecore-jss-dev-tools\dist\cjs\deploy.js:21:28)

    at Object.<anonymous> (C:\projects\sc104nextjsnewinst\nextjs\node_modules\@sitecore-jss\sitecore-jss-cli\dist\cjs\scripts\deploy.config.js:58:45)

    at Generator.next (<anonymous>)

    at fulfilled (C:\projects\sc104nextjsnewinst\nextjs\node_modules\@sitecore-jss\sitecore-jss-cli\dist\cjs\scripts\deploy.config.js:5:58) {

  errno: -4048,

  syscall: 'mkdir',

  code: 'EPERM',

  path: 'C:\\inetpub\\wwwroot\\sc104nextjsnewinstsc.dev.local\\App_Config\\Include\\zzz'

}

Resolution:

PowerShell must run in admin mode before executing the concerned command

Summary:

1. XPE Error:

"Page: No renderer for form element type {D819B43E-C136-4392-9393-8BE7FCE32F5E}"

Resolution:

Install hotfix

2. Form Submit Error:

Unexpected token '<', "<!DOCTYPE "... is not valid JSON

Resolution:

In connected mode, don't send '' in place of sitecoreApiHost

References:

https://blogs.perficient.com/2023/08/08/integrate-sitecore-form-into-a-jss-app-react-next-js-in-headless-architecture/

https://support.sitecore.com/kb?id=kb_article_view&sysparm_article=KB0641167

https://doc.sitecore.com/xp/en/developers/hd/latest/sitecore-headless-development/walkthrough--getting-started-with-jss-for-react.html