Workflow: Implement custom pages with React

This article helps you solve the challenge of integrating personalized and unique functionality into your Zendesk help center. By guiding you through the process of adding custom pages to your Guide Enterprise plan, it explains how to develop, bundle, and embed custom pages using technologies such as React.js and Node.js. For instance, you can create a custom VIP Support sign-up page that seamlessly fits with your existing help center design, providing a cohesive and tailored user experience.

Note: 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. Zendesk doesn’t support custom themes and they don’t update automatically with new features. For more information, see the article: About the standard theme and custom themes in your help center.

This single-page app example uses React with TypeScript for the frontend and Node.js for the backend. Tailwind CSS styles the app, and Nodemailer handles email confirmations for new users who successfully sign up.

Since this is a React app, the example covers the Webpack steps to compile it into a single file. Embed the file in your help center theme and upload it. Follow the sections below for each set of steps:

• Develop: Create the custom page using React with TypeScript and Node.js.
  • React
  • Node.js
• Bundle: Configure Webpack to bundle the custom page
• Embed: Integrate the project into your theme and publish it to the help center

Note: If you don't want to integrate with a backend or use TypeScript, check out the boilerplate to start building your own single-page app.

Develop: Create the custom page using React with TypeScript and Node.js.

Custom pages let you develop using any preferred web tech stack. Many prefer using React.js with Node.js for backend development. Each technology has its own nuances and specifications. Here are some technical considerations:

React

Use Create React App for custom pages since it’s a single-page application framework. The VIP Support sign-up page above makes two requests. One generates a secure token for backend authentication. The other submits actual data.

The example custom page changes user profiles and organizations within Zendesk. If your page makes similar requests, validate data from the frontend before the request. Backend validation is essential, but frontend validation ensures clean data, especially from user inputs.

Remember, a custom page is just one part of your help center. Ensure any functionality, branding, or styling aligns with your help center as a whole.

Consider these design aspects:

• Authentication: Determine who can access this page: agents, all authenticated users, or every user

• Navigation:

  • Don't develop a header or navigation on your custom page. The Guide team of your account sets these. The custom page inherits the current theme's header and navigation.

  • Place this page appropriately within the help center. Like the functionality, the custom page exists outside the default help center schema. Users access these pages via links in any help center template or predefined page like your home page. Custom page URLs follow this format:

    https://{domain_name}/hc[/{locale}]/p/{page_name}

• Page styling: Select styling libraries that align with the help center theme. Ensure your font and color palette match the existing theme.

• Image handling: Since you'll configure and bundle your custom page manually, storing images or assets locally won't work. Upload them to your help center theme before embedding. For a step-by-step guide, see the article: Using your own theme assets for help center.

Node.js

Custom pages provide a blank canvas to build a personalized experience for your visitors. With tools like Node.js and Express, you can directly connect to existing systems and databases. You can also create new services with your preferred tech stack, integrating them with your help center for a seamless user experience.

The example app uses the functions below.

• A developed Express API that receives the user and organization information submitted by the frontend form.

• Send API requests to Zendesk Support to create and update the relevant user and organization with node-fetch.

• Validate the form submission data using validator.js.

• Send a confirmation email notification to the user on successful form submission with Nodemailer.

Be mindful of security and protect your API routes when building server-side custom page services. Use tools such as JWT to secure your application by building request authentication. For more details on JWT, see this article from JWT website: JSON Web Token Introduction.

The example app uses the authentication below.

• An authentication endpoint for the frontend to request a JWT token to authorize requests to the form submission API.

• Authentication modules that generate and verify JWT tokens using jsonwebtoken.

Depending on the application you build, consider your CORS (Cross-Origin Resource Sharing) policy. Ensure that the routes receiving requests from the client side have CORS enabled. If you know the domains that send the requests, specify these domains explicitly. Otherwise, use the wildcard *. For more information on CORS, see this article from Mozilla's website: Cross-Origin Resource Sharing (CORS).

Bundle: Configure Webpack to bundle the custom page

Once you complete the development of your custom page, bundle your React app using Webpack. Since all custom pages need to be embedded within your theme, compile the custom page into a single HTML file. The Create React App comes with its own bundling and optimization. However, since the goal is to return a single index.html file, the example has its own webpack configuration to streamline this process.

Embed: Integrate the project into your theme and publish it to the help center

After building your application, embed it into your help center. Navigate to the newly created build directory. Here you will find a few files that are necessary to create the new custom page.

• index.html
• static/css/bundle.min.css
• static/bundle.min.js

The index.html file is the code to put into the custom page. Access the JavaScript and CSS created for the project. First, upload the JavaScript and CSS file as assets into your help center. Then, copy the code from your index.html file into the custom page and adjust the file paths to the assets.

Find an example below of how this appears in the code editor.

Once finished, publish your custom page. For additional resources about managing content in your help center, see the article: Guide resources.