Building a React app, Part 1: Introduction
Thanks for visiting this older post. If you’re interested in CORS access to the eSignature REST API, check out its new CORS feature:
- CORS is here!
- OAuth for CORS applications
- Live CORS examples on CodePen
- Building a bulletproof CORS application
- DocuSign Developer Center CORS documentation
The original post:
In this multipart series, I’ll cover the steps needed to add the DocuSign eSignature API to a React app, including two patterns for integrated OAuth authentication.
The React framework for JavaScript is very popular, and is often seen as the leader among its two nearest competitors, Vue and Angular.
In this series, I’m focusing on React for JavaScript (React) and “React” will always refer to React for JavaScript. React Native is related; it’s a framework for writing native mobile applications. If you’re interested in React Native, you should also check out Flutter. React can also be used to build native desktop applications for Windows, MacOS, and Linux via the Electron framework. In a future blog post series, I’ll show you how.
React has become popular due to its speed and declarative, component-based approach for building apps. The front page of the React website includes a live demonstration of React’s top features for developers.
React is a framework for building applications. React apps consist of multiple components that together comprise your application. As a framework, React offers many options for implementing your application For example, React components can be built as classes or as functions. For my example app, I’m using React class components, but function components with React Hooks could also be used.
React was designed to create apps that run on the browser, and that’s how I use it in this example. When a React application runs on the browser, it is literally executing its code within the browser. The server behind the web address used for a React application (for example, apps.example.com/my_react_app) only needs to download the application’s JavaScript code, React libraries, and other supporting content. The server used for the application’s web address can be a simple web server such as an AWS S3 bucket. React apps can also run on a server, but that’s outside the scope of this series.
When the React app on the browser wants to communicate with a server, it uses the Ajax technique to make HTTPS requests. Different Ajax libraries are available; I use the JavaScript Fetch library, which is natively included in modern browsers.
In addition to executing locally on the browser, another great feature of React apps is that they do not need to make a round trip to a server to fetch a new page. React apps that do not cause new page downloads are categorized as Single Page Applications (SPAs). React SPA apps can immediately generate and display new content locally on the browser. Gmail is a leading example of an SPA with multiple pages.
Different techniques are available for managing multiple, locally created pages from an app, including the popular React Router library. Here’s a tutorial article on it. For this example app, we’ll use a simpler technique for managing the app’s two different pages.
Authentication
This example application will enable the user to login to DocuSign. Since the login flow is hosted by the application running in the browser, the Implicit Grant flow is used. For different use cases where the user does not have or need a DocuSign account, the JWT Grant flow would be used. But the JWT Grant flow can only be used by a secure server application. So the JWT Grant would be used by a server application for the React app. In some cases, the PowerForm API can be used when the user does not have a DocuSign user account.
I’ll discuss the authentication issues more in the next installment of this series.
Calling the DocuSign eSignature REST API with CORS
As mentioned above, I’ll use the Fetch library to make HTTPS Ajax requests from the app running in the browser to DocuSign. But there’s a wrinkle: due to information security issues, browser applications can normally only make HTTPS Ajax requests to the server the browser was initially loaded from, its origin. This is the Same-origin Policy.
In this case, the example app will be loaded from apps.example.com/my_react_app, but I want to make requests to demo.docusign.net (or to a DocuSign production platform). The request will fail unless the DocuSign API server implements the Cross-Origin Resource Sharing (CORS) standard. DocuSign has implemented CORS for several products so far, and CORS is planned for the eSignature REST API in the future. If your company would like DocuSign to implement CORS sooner, ask your DocuSign Sales or Customer Service contact to add your organization’s information to the internal ticket PORTFOLIO-1100.
Private CORS proxy server
Meanwhile, the workaround is a private CORS proxy server for your application. See this post, which discusses how to configure the Apache server to be a CORS proxy. In addition, I’ve written and tested a CORS proxy configuration file for the popular Nginx web server.
The UX library
For any web app, the User Experience (UX) is a key ingredient. For this example web app, I’ll use the popular React Bootstrap library. It takes care of the basic look and feel of the app and provides optional components that can be used as needed.
I use the popular react-toastify library for notifications.
Conclusion
React enables developers to create high-performance web applications for internal and external use cases. In this series I’ll show you how to add Implicit Grant and the DocuSign eSignature REST API to a React app. To continue, see Building Single-Page Applications with DocuSign and CORS: Part 2.
