Single Page Applications (SPAs) have become the go-to approach for building fast, responsive web interfaces. Instead of loading a new HTML page every time a user clicks something, SPAs load everything up front and then update the page dynamically. This gives users a smoother, app-like experience in the browser.
At a high level, SPAs work by handling routing and rendering on the client side. After the initial load, all page interactions are managed with JavaScript. When a user navigates or performs an action, the app requests only the data it needs from the server, usually through APIs, and updates just part of the screen. That means there will be fewer full-page reloads, faster transitions, and a more fluid user experience.
Single Page Applications for NetSuite ERP are built inside an SDF SuiteApp project, use SuiteScript 2.1, require two script types (SPA server and client), and need a build step to transpile/convert JSX/ESM into the AMD/RequireJS modules NetSuite expects.
npm i -g @oracle/suitecloud-cli
suitecloud project:create --type SUITEAPP --projectid com.myorg.myspa --projectname "My SPA SuiteApp" --publisherid com.myorg --projectversion 1.0.0
Inside your project put the SPA sources under:
src/SuiteApps/<publisherid>/<spa-folder>/
├─ SpaClient.jsx (or .js produced after build)
├─ SpaServer.js
└─ assets/...
Then add a singlepageapp object XML in src/Objects, e.g. src/Objects/custspa_appdashboard.xml:
<singlepageapp scriptid="custspa_appdashboard">
<name>My SPA Dashboard</name>
<description>SPA example for ERP</description>
<url>app-dashboard</url> <!-- path after /spa-app/<appID>/ --><folder>[/SuiteApps/com.myorg.myspa/app-dashboard/]</folder>
<clientscriptfile>[/SuiteApps/com.myorg.myspa/app-dashboard/SpaClient.js]</clientscriptfile>
<serverscriptfile>[/SuiteApps/com.myorg.myspa/app-dashboard/SpaServer.js]</serverscriptfile>
<assetsfolder>[/SuiteApps/com.myorg.myspa/app-dashboard/assets/]</assetsfolder>
<audienceallroles>T</audienceallroles>
</singlepageapp>
That XML pattern (tag <singlepageapp …>) is the official way to register the SPA URL, folder and the client/server script files.
The server script uses @NApiVersion 2.1 and @NScriptType SpaServerScript.
It must export initializeSpa(context); the context object can add stylesheets and do checks (audience, preliminary data, error/denial, etc.).
Example SpaServer.js:
/**
* @NApiVersion 2.1
* @NScriptType SpaServerScript
*/
import runtime from 'N/runtime';
import log from 'N/log';
export const initializeSpa = (context) => {
const user = runtime.getCurrentUser();
log.debug({ title: 'SPA init', details: `User ${user.id}` });
// optionally add an assets CSS file (path is relative to the assets folder)
context.addStyleSheet({ relativePath: '/css/spa.css' });
// throw a string or Error to block loading if needed// if (user.id !== SOME_ID) throw 'Unauthorized user';return;
};
SpaClient.jsx (source — transpile this before deploy; see next step):
// SpaClient.jsx (source in JSX/TSX)import HelloWorld from './HelloWorld.jsx';
export const run = (context) => {
// layout types: 'application' fills the viewport; see docs
context.setLayout('application');
// render the UIF root component (JSX)
context.setContent(<HelloWorld />);
// optionally return a promise if asynchronous work is needed
};
HelloWorld.jsx (root component using UIF components — imports shown per UIF catalog):
import { ContentPanel, Heading, Button } from '@uif-js/component';
export default function HelloWorld() {
return (
<ContentPanel>
<Heading level={1}>My SPA (JSX)</Heading>
<p>Welcome to the SPA running inside NetSuite ERP.</p>
<Button onClick={() => alert('Clicked!')}>Click me</Button>
</ContentPanel>
);
}
Important: NetSuite expects AMD/RequireJS modules and UIF ESM components; your SPA sources (JSX/TSX + ESM import) must be transpiled and converted before deploying. The sample SPA SuiteApps in Oracle’s GitHub include a gulpfile that performs the build/bundle/convert steps (transpile JSX → JS, convert import/export to NetSuite module format). You can also use your own toolchain (webpack/rollup + Babel) as long as output lands in the Single Page Application folder as plain JS the SDF project references. Oracle Documentation
Example high-level build flow (in package.json):
"scripts": {"build": "gulp build", // or: webpack --config webpack.spa.config.js"validate": "suitecloud project:validate","deploy": "suitecloud project:deploy"}
The key is the build output must put the compiled SpaClient.js and SpaServer.js (and assets) into the SPA folder referenced by your singlepageapp XML.
Add the Server Side Scripting feature to your manifest so SDF includes required features:
<dependencies>
<features>
<feature required="true">SERVERSIDESCRIPTING</feature>
</features>
</dependencies>
The docs explicitly recommend adding SERVERSIDESCRIPTING to manifest.xml for SPA SuiteApps. Oracle Documentation
suitecloud project:validate # flags available e.g. --applyinstallprefs
suitecloud project:deploy
SDF deploy will package the project (per deploy.xml) and upload the referenced objects/files to the target account. Use a sandbox/account you control when testing.
Access the SPA URL defined in the SPA object (/spa-app/<ApplicationID>/<url>). The Single Page Application server script runs first (initializeSpa), then the client script loads and run(context) is called; the UI shows a loading icon until run resolves. Confirm audiences/roles in the SPA object XML so only intended users see it.
NetSuite 2025 introduces support for JSX within its SPA framework. While it’s not React, the syntax and approach are similar.
Yes, SPAs can interact with NetSuite data using SuiteScript APIs, making them great for building custom UI flows.
Yes. Since SPAs only load data as needed and avoid full page reloads, they provide faster navigation and a smoother experience.
SPAs are supported in NetSuite 2025.1 and above. Users must have SDF enabled and appropriate permissions to deploy SPA scripts.
Engineering Manager at UnlockCommerce, with a robust background in software development and team leadership. Marcos specializes in guiding engineering teams to deliver high-quality, scalable, and efficient solutions tailored to meet client needs. His expertise in SuiteCommerce and Shopify and deep understanding of NetSuite and eCommerce systems ensure seamless execution and innovative results for our clients. Marcos is dedicated to fostering collaboration and driving excellence across all technical initiatives.
Learn how Leo Berbee modernized its B2B operations by moving from disconnected systems to automated SuiteCommerce workflows, improving efficiency, flexibility, and customer experience.
Generic Core Web Vitals advice can mislead SuiteCommerce teams. Here’s how to focus performance investments where they actually impact buyers.
Agentic commerce makes buying easier than ever. But for Shopify merchants with complex pricing, inventory, and brand experiences, convenience can come at a cost.