Create NetSuite React App

A CLI tool to quickly scaffold a NetSuite React TypeScript application with modern tooling.

⚠️ Important: Use npx create-netsuite-react-app (not npm install). This is a scaffolding tool, not a project dependency.

Quick Start

npx create-netsuite-react-app my-netsuite-app
cd my-netsuite-app
npm install
npm run dev

Requirements

Node.js: >= 18.0.0
npm: >= 9.0.0

Version Management (Optional)

This project supports Volta for automatic Node.js/npm version management:

With Volta: Versions are automatically pinned to Node.js 24.1.0 + npm 11.3.0
Without Volta: Use any compatible Node.js (>=18.0.0) and npm (>=9.0.0) versions

To install Volta (recommended but optional):

curl https://get.volta.sh | bash  # macOS/Linux
# or visit https://volta.sh for Windows

What You Get

✅ Modern React with TypeScript and Vite
✅ NetSuite Integration ready-to-go SuiteScript and SDF structure
✅ Development Tools with hot reload and type checking
✅ Build System that outputs to NetSuite FileCabinet structure
✅ Project Setup script for easy configuration

🚀 Deploying to NetSuite

SuiteCloud Extension Commands

The recommended approach for deploying your app to NetSuite is through the SuiteCloud Extension for Visual Studio Code using the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).

Essential Commands:

Command	When to Use	Notes
`SuiteCloud: Set Up Account`	First time deployment or new NetSuite account	✅ Safe to run multiple times 🔧 Walks through authentication setup
`SuiteCloud: Deploy Project`	Every time you want to push updates	🚀 Main deployment command 📦 Uploads your entire project
`SuiteCloud: Set Up Project`	⚠️ NEVER USE THIS	❌ The npm template already handles project setup ❌ Running this may cause configuration issues

Quick Deployment Steps:

First Time: Run SuiteCloud: Set Up Account to authenticate
Every Update: Run SuiteCloud: Deploy Project to push changes
Never Run: SuiteCloud: Set Up Project (template handles this)

⚠️ Important: Project Name Changes

Critical information for NetSuite deployment:

If you change your project name after initial setup using npm run setup, be aware that:

The next deployment to NetSuite via the SuiteCloud Extension for Visual Studio Code will create entirely new project files
This includes newly named script files, deployments, and file cabinet directories
Your previous project files will remain in NetSuite under the old name
You may need to manually clean up old files to avoid having multiple versions

CRITICAL STEPS after changing project name:

Run npm run setup (updates project configuration)
MUST run npm run build (rebuilds React app in new directory structure)
Deploy using SuiteCloud Extension

Common Issue: If your deployed app shows a blank page after renaming, it's because the SuiteScript handler is looking for React files in the old directory. Always rebuild after renaming.

Best Practice: Choose your project name carefully during initial setup to avoid duplicate files in NetSuite.

Generated Project Structure

my-netsuite-app/
├── 📁 frontend/           # React TypeScript application
│   ├── 📁 src/            # React source code
│   ├── index.html         # HTML template
│   └── tsconfig.json      # TypeScript configuration
├── 📁 Objects/            # NetSuite script deployment XMLs
├── 📁 FileCabinet/        # File cabinet resources & SuiteScripts
│   └── 📁 SuiteScripts/   # Built app & SuiteScript handlers
│       └── 📁 {projectName}/ # Project-specific directory
├── 📄 package.json       # Dependencies & scripts (root)
├── 📄 vite.config.ts     # Build configuration
├── 📄 setup.js           # Project configuration script
├── 📄 project.json       # NetSuite project settings
└── 📄 tsconfig.node.json # Node TypeScript config

Commands

All commands run from the project root:

npm run dev - Start development server
npm run build - Build for NetSuite deployment
npm run setup - Configure project names and settings
npm run preview - Preview production build

Compatibility

This package works with or without Volta:

Volta users: Get consistent, pinned versions automatically
Non-Volta users: Use any compatible Node.js/npm versions (will warn if incompatible)

Happy coding! 🚀