Introduction

Although we provide a comprehensive ReactJS template for building out a custom web client, you may want to use something different such as Next.js.

Node.js & Next.js

When integrating the PureWeb SDK with a Next.js project, you may encounter issues with certain Node.js modules that aren't intended for front-end use. This article documents a real-world scenario and explains how to resolve such issues, ensuring a smoother integration process.

NOTE: Whether using our React.js template or porting over to a more custom solution such as this, once you begin customizing your web client the responsibility for hosting, maintaining, supporting and testing it is that of the license-holder.

When porting from the React-based project into a Next.js environment you may encounter compiler errors related to Node.js-specific modules (tls and  fs ). These modules are required by the PureWeb SDK but are only meant for server-side use and not for the browser. See below for examples

Module Not Found Error

  • Error: Module not found: Can't resolve 'tls'
  • Cause: Next.js tried to include the tls module, which is not available in the browser environment.

File System Module Error

  • Error: Module not found: Can't resolve 'fs'
  • Cause: Similar to tls, the fs module is also specific to Node.js and not available in the browser.

These errors typically arise because Next.js, by default, may attempt to bundle these Node.js modules into the client-side code.

Solution

To resolve these issues, we need to adjust the Webpack configuration in the Next.js project to exclude these Node.js modules from the client-side bundle.

Step-by-step guide

Modify the Next.js Webpack Configuration

Open your Next.js configuration file (next.config.js) and add a custom Webpack configuration to handle the module resolution issue.

next.config.jsmodule.exports = { 
    webpack(config) {
        config.resolve.fallback = { 
            // Preserve existing fallbacks
            config.resolve.fallback, 
            // Add fallbacks for problematic modules      
            fs: false, tls: false, }; 
        return config; }, };
  • config.resolve.fallback: This Webpack option allows you to specify fallbacks for modules that cannot be resolved. By setting fs and tls to false, you're instructing Webpack to ignore these modules in the client-side bundle.

This configuration effectively silences the errors caused by these modules and allows your Next.js application to build and run without issues.

Testing the Configuration

After making the above changes:

  1. Rebuild your Next.js project,
  2. Ensure that the application builds successfully without the previous module errors,
  3. Verify that the PureWeb SDK functions as expected in the browser environment.

Additional Tips

  • Check Dependencies: Ensure that other dependencies in your project do not also try to include Node.js-specific modules. Apply similar fallbacks as needed.
  • Environment-specific code: Use environment checks to conditionally import or use modules that are specific to the server-side, ensuring they are not included in the client bundle.
if (typeof window === 'undefined') { 
    // Code here runs only on the server  
    const someServerSideOnlyModule = require('some-server-side-only-module');
}

Conclusion

By configuring Webpack to handle Node.js-specific modules properly, you can successfully integrate the PureWeb SDK into your Next.js application without encountering build errors. This approach ensures a seamless transition from a standard React environment to Next.js, leveraging the server-side rendering capabilities while avoiding client-side issues.

This solution will help developers avoid similar issues in the future, providing a smoother development experience when working with Next.js and PureWeb SDK.