Workflow: Implement custom pages with React

<p>This article helps you integrate personalized and unique functionality into your help center. It guides you through the process to add <a href="https://support.zendesk.com/hc/en-us/articles/4409012911770-Creating-custom-pages-in-the-help-center" target="_blank" rel="noopener noreferrer">custom pages</a> to your Knowledge Enterprise plan and explains how you can develop, bundle, and embed custom pages with React.js and Node.js.</p><p>For example, you can create a custom VIP Support signup page to provide a cohesive and tailored user experience.</p><p><img src="https://support.zendesk.com/hc/article_attachments/7856362231962" alt="single page app example" width="654" height="620"></p><p>This single-page app example uses <a href="https://reactjs.org/" target="_blank" rel="noopener noreferrer">React</a> with TypeScript for the frontend and <a href="https://nodejs.org/" target="_blank" rel="noopener noreferrer">Node.js</a> for the backend. <a href="https://tailwindcss.com/" target="_blank" rel="noopener noreferrer">Cascading Style Sheets (CSS)</a> styles the app, and <a href="https://www.npmjs.com/package/nodemailer" target="_blank" rel="noopener noreferrer">Nodemailer</a> manages email confirmations for new users who successfully register.</p><p>Because you work with a React app, the example covers the Webpack steps to compile it into a single file. You embed the file in your help center theme and upload it. Follow the sections below for each set of steps:</p><p>If you don't want to integrate with a backend or use TypeScript, see the <a href="https://github.com/zendesk/custom-pages-react-boilerplate" target="_blank" rel="noopener noreferrer">boilerplate</a> to start your own single-page app.</p><div class="note">
<span class="title">Disclaimer:</span> Use the theme editor to modify page templates, CSS, or JavaScript for a standard theme, or create your own theme. It saves as a custom theme. Custom themes and custom code aren't supported, and <a href="https://support.zendesk.com/hc/en-us/articles/4408821255834-About-the-standard-theme-and-custom-themes-in-your-help-center" target="_blank" rel="noopener noreferrer">themes</a> don't update automatically with new features. Reach out to a web developer for code support.</div><div style="margin-bottom: 20px; text-align: right;">
<button id="master-toggle" class="btn fw-semibold text-dark" data-action="expand" style="background-color: #DEF991; border: none; outline: none; border-radius: 7px; padding: 10px 20px; font-size: 15px; transition: background-color 0.2s ease;" onmouseover="this.style.backgroundColor='#cbef6d'" onmouseout="this.style.backgroundColor='#DEF991'">
Expand all tabs
</button>
</div>
<script>
document.addEventListener('DOMContentLoaded', function () {
const toggleBtn = document.getElementById('master-toggle');

toggleBtn.addEventListener('click', function () {
const action = this.getAttribute('data-action');
const headers = document.querySelectorAll('.accordion');

headers.forEach(header => {
const isActive = header.classList.contains('active');
const panel = header.nextElementSibling; // Grabs the corresponding .panel container

if (action === 'expand' && !isActive) {
// Open it by simulating a standard click
header.click();
} else if (action === 'collapse' && isActive) {
// Close it by simulating a standard click
header.click();
}
});

// Flip button text and states
if (action === 'expand') {
this.setAttribute('data-action', 'collapse');
this.textContent = 'Collapse all tabs';
} else {
this.setAttribute('data-action', 'expand');
this.textContent = 'Expand all tabs';
}
});
});
</script><div class="accordion"><h3 id="h_01FW4AFNS1AXWPAV7RW1JDRWBD">Step 1: Develop the custom page with React, TypeScript, and Node.js</h3></div><div class="panel">
<p>Custom pages let you develop with any preferred web technology stack. Many developers prefer React.js with Node.js for backend development. Each technology has its own nuances and specifications. Consider the following technical points:</p>
<h4 id="h_01J5D8DGFTDKEDW72WEBBYW9KD">React</h4>
<p>Use <a href="https://create-react-app.dev/docs/getting-started/" target="_blank" rel="noopener noreferrer">Create React App</a> for custom pages because this framework supports single-page applications. The VIP Support signup page makes two requests: one request generates a secure token for backend authentication, and the other submits actual data.</p>
<p>The example custom page changes user profiles and organizations within the system. If your page makes similar requests, validate data from the frontend before you send the request. Backend validation plays a crucial role, but frontend validation ensures clean data, especially from user inputs.</p>
<p>Remember that a custom page forms just one part of your help center. Ensure any functionality, branding, or styling aligns with your help center as a whole.</p>
<p>Consider these design aspects:</p>
<ul>
<li data-list-item-id="e37e97344824dbfc6fbbb731b8af79e5b">Specify who can access this page, such as agents, all authenticated users, or every user</li>
<li data-list-item-id="e49fa343996b54931ef7531379ecb64d2">Do not create a header or navigation on your custom page. The custom page inherits the header and navigation of the current theme. Position this page appropriately within the help center because the custom page exists outside the default help center schema. Users reach these pages through links in any help center template or predefined pages, such as your home page. Custom page URLs use the format <code>https://{domain_name}/hc[/{locale}]/p/{page_name}</code>.</li>
<li data-list-item-id="e0e5fac0520919f702e006c0e34c0c717">Select styling libraries that fit the help center theme. Ensure your font and color palette match your existing theme.</li>
<li data-list-item-id="ea4709081ec68d29bc92dfc0bc8e8b859">Because you manually configure and bundle your custom page, local storage of images or assets doesn't work. Upload them to your help center theme before you embed them. For step-by-step instructions, see <a href="https://support.zendesk.com/hc/en-us/articles/4408829155226-Using-your-own-theme-assets-for-help-center" target="_blank" rel="noopener noreferrer">Using your own theme assets for help center</a>.</li>
</ul>
<h4 id="h_01J5D8DC4PF19GD46ET8E6R59V">Node.js</h4>
<p>Custom pages give you a blank canvas to build a personalized experience for your visitors. With tools such as Node.js and Express, you can connect directly to existing systems and databases. You can also create new services with your preferred tech stack and integrate them with your help center for a seamless user experience.</p>
<p>The example app uses the functions below:</p>
<ul>
<li data-list-item-id="e8d8fd8e822645588c485f6e605985abd">The developers created an Express <a href="https://github.com/zendesk/custom-pages-example/blob/main/backend/app.js#L183" target="_blank" rel="noopener noreferrer">Application Programming Interface (API)</a> that receives the user and organization information submitted by the frontend form</li>
<li data-list-item-id="ea1b9812db850978b96f6bb359778039e">The app sends API requests to Support to create and update the relevant user and organization with <a href="https://www.npmjs.com/package/node-fetch" target="_blank" rel="noopener noreferrer">node-fetch</a>
</li>
<li data-list-item-id="e87661035a7ee473c05c8080a3caefb4d">It validates the form submission data with <a href="https://www.npmjs.com/package/validator" target="_blank" rel="noopener noreferrer">validator.js</a>
</li>
<li data-list-item-id="e0e439d39e7819395ea678a7979390432">The app sends a <a href="https://github.com/zendesk/custom-pages-example/blob/main/backend/mailer.js" target="_blank" rel="noopener noreferrer">confirmation email notification</a> to the user on successful form submission with <a href="https://www.npmjs.com/package/nodemailer" target="_blank" rel="noopener noreferrer">Nodemailer</a>
</li>
</ul>
<p>Protect your API routes carefully when you build server-side custom page services. Use tools such as JSON Web Token (JWT) to secure your application to establish request authentication. For more details on JWT, see <a href="https://jwt.io/introduction" target="_blank" rel="noopener noreferrer">JSON Web Token Introduction</a>.</p>
<p>The example app uses the authentication described below:</p>
<ul>
<li data-list-item-id="e7bbf28ac83146bd2001b1460392abe78">The developers created an <a href="https://github.com/zendesk/custom-pages-example/blob/main/backend/app.js#L189" target="_blank" rel="noopener noreferrer">authentication endpoint</a> that the frontend uses to request a JWT token and authorize requests to the form submission API</li>
<li data-list-item-id="ea2d120ae753a273d51c4e0dee98c167c">The <a href="https://github.com/zendesk/custom-pages-example/blob/main/backend/auth.js" target="_blank" rel="noopener noreferrer">authentication modules</a> generate and verify JWT tokens with <a href="https://www.npmjs.com/package/jsonwebtoken" target="_blank" rel="noopener noreferrer">jsonwebtoken</a>
</li>
</ul>
<p>Depending on the application you build, consider your cross-origin resource sharing (CORS) policy. Ensure that the routes that receive requests from the client side have CORS activated. If you know the domains that send the requests, specify these domains explicitly. Otherwise, configure the wildcard <code>*</code>. For more information on CORS, see <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS" target="_blank" rel="noopener noreferrer">Cross-Origin Resource Sharing (CORS)</a>.</p>
</div><div class="accordion"><h3 id="h_01FVWFHB76BZVMF8RFZRRED8EC">Step 2: Configure Webpack to bundle the custom page</h3></div><div class="panel"><p>After you complete the development of your custom page, bundle your React app with Webpack. Because your theme needs to embed all custom pages, compile the custom page into a single Hypertext Markup Language (HTML) file. The <a href="https://create-react-app.dev/docs/getting-started/" target="_blank" rel="noopener noreferrer">Create React App</a> includes its own build and optimization tools. However, because you aim to return a single <code>index.html</code> file, the example uses its own <a href="https://github.com/zendesk/custom-pages-example/blob/main/frontend/config/webpack.config.js" target="_blank" rel="noopener noreferrer">webpack configuration</a> to simplify this process.</p></div><div class="accordion"><h3 id="h_01FVWFHHP8AMFNYYQBJZQW24VP">Step 3: Embed and integrate the project into your theme and publish it to the help center</h3></div><div class="panel">
<p>After you build your application, embed it into your help center. Navigate to the newly created build directory. You will find a few files needed to create the new custom page:</p>
<ul>
<li data-list-item-id="e3b6bc6d727b7b2b549b920b26884d4a5"><code>index.html</code></li>
<li data-list-item-id="ed24ee1da458bd8bdf2a4b1d71c05e20d"><code>static/css/bundle.min.css</code></li>
<li data-list-item-id="ed0a0c90ccdeb5520cb640d7757033a31"><code>static/bundle.min.js</code></li>
</ul>
<p>The <code>index.html</code> file contains the code you put into the custom page. Access the JavaScript and CSS created for the project. First, upload the JavaScript and CSS files as <a href="https://support.zendesk.com/hc/en-us/articles/4408829155226-Using-your-own-theme-assets-for-help-center" target="_blank" rel="noopener noreferrer">assets</a> into your help center. Then, copy the code from your <code>index.html</code> file into the custom page and adjust the file paths to point to the assets.</p>
<p>See an example below of how this appears in the code editor.</p>
<p><img src="https://support.zendesk.com/hc/article_attachments/7856384714266" alt="Image_of_CSS_in_the_help_center_code_editor.png"></p>
<p>After you finish, publish your custom page. For additional resources about to manage content in your help center, see <a href="https://support.zendesk.com/hc/en-us/articles/4408823842842-Guide-resources" target="_blank" rel="noopener noreferrer">Knowledge resources</a>.</p>
</div>