When to pair a Next.js front end with NetSuite ERP

NetSuite · Architecture

Many NetSuite companies sell something that does not fit a catalog store: software, licenses, services backed by a lot of documentation. For them the website is mostly content, and the ERP is where the money is. This guide explains when a Next.js front end on top of NetSuite makes sense, how the two sides talk, and what to watch for.

What is a hybrid Next.js and NetSuite architecture?

It is a website where Next.js serves every page people read (marketing, product and documentation pages) while NetSuite stays the system of record for customers, orders, licenses and billing. The front end reads from and writes to NetSuite through its APIs, so there is one source of truth for anything with money or a contract attached.

We built this for an engineering-software company. Their public site is content-heavy: product pages, technical documentation and release information. Their business runs in NetSuite. Splitting the two let each side do what it is good at, without duplicating customer or order data in a second database.

When does it beat SuiteCommerce alone?

SuiteCommerce is NetSuite's own commerce product, and for many stores it is the right answer. Oracle lists secure shopping, checkout and account management, B2B and B2C support, faceted search, a CDN, Site Management Tools, and theme and extension customization. If you sell a physical catalog and want those features out of the box, start there.

A hybrid build pays off when the shape of the business is different:

Performance is often the deciding factor for content sites. Google's Core Web Vitals ask for a Largest Contentful Paint within 2.5 seconds, an Interaction to Next Paint under 200 milliseconds and a Cumulative Layout Shift under 0.1. Google says good scores align with what its core ranking systems seek to reward. Owning the rendering layer makes those targets easier to hold.

How do the two sides talk?

Through NetSuite's integration layer, from the server side of Next.js only. The browser never calls NetSuite directly.

• REST web services for standard records and queries. Oracle recommends REST web services for system-to-system integrations: no server-side scripting is needed, and they support SuiteQL. A SuiteQL query is a POST to the suiteql resource.
• RESTlets when you need a custom endpoint. A RESTlet is a deployed script, and Oracle notes it can handle all the actions of a business flow in one call. We use them for operations that touch several records at once.
• OAuth 2.0 client credentials for authentication. It is a machine-to-machine flow with no user interaction. You upload a certificate's public key and map it to an application, an entity and a role, so the integration acts with exactly the permissions of that role.

On the Next.js side, cache what does not change often. With Incremental Static Regeneration a page is prerendered and served from cache; a revalidate time refreshes it in the background, and revalidatePath or revalidateTag invalidate it on demand. If revalidation throws, Next.js keeps serving the last successful version, so a NetSuite outage does not take your documentation down with it.

What breaks first, and how do you prevent it?

In our experience, four things, roughly in this order.

1. Concurrency. SOAP and REST web services and RESTlets share one account-level concurrency limit. A traffic spike on the website can starve the integrations that run the business. Cache reads, queue writes and never call NetSuite once per page view for data that changes daily.
2. Stale content. A product changes in NetSuite and the site still shows the old version. Decide for each type of data how fresh it must be, and trigger on-demand revalidation when it changes rather than shortening every cache. If you run several instances, the default cache is per instance, so on-demand revalidation needs a shared cache handler to reach all of them.
3. Authentication. Certificates expire or get revoked, and then you need a new mapping. Client credentials setup is not copied from production to sandbox or Release Preview accounts, and a sandbox refresh clears it. Put the renewal date in a calendar and the setup steps in a runbook.
4. Debugging across two systems. When an order fails, the cause can be on either side. Log a correlation ID in Next.js and pass it into NetSuite so the script execution log tells the rest of the story. We wrote about finding silent errors in NetSuite for that half.

How do you migrate without a big-bang launch?

Route by route. Next.js can fall back to proxying requests to your existing site after it has checked its own routes, using fallback rewrites. You move one section, say the documentation, and every other URL keeps being served by the old site with no change to the rewrite configuration.

1. Measure first. Record Core Web Vitals, organic traffic and conversions for the section you are about to move.
2. Move one section. Content pages are the safest start, because they read from NetSuite but rarely write to it.
3. Redirect what changed. Use permanent redirects for URLs that change. Next.js answers them with a 308 status, which tells browsers and search engines to cache the redirect.
4. Compare. Check the same numbers after a few weeks before you move the next section.
5. Move the transactional flows last, once the integration, logging and caching have proven themselves on simpler pages.

Where should you start?

Write down which pages are content and which are transactions, and where each piece of data lives today. If most of your site is content and NetSuite already holds the customers, orders and licenses, a hybrid build is worth a serious look. If you sell a catalog and need a cart this quarter, SuiteCommerce will get you there faster.

If you want help deciding, or a plan for moving your first section, talk to our NetSuite team.