How To Properly Version Control Your NetSuite Project
When I first started reviewing NetSuite projects years ago, I noticed a pattern.
Repositories would proudly hold a SuiteScripts folder — and that's it.
No manifest.xml. No Objects. No deploy.xml.
Just a handful of .js files sitting in a folder like souvenirs from a lost deployment.
I still remember the first time I had to onboard into one of those setups. We had to manually recreate script records, redeploy each file through the UI, and guess which workflow went with which script. We spent days trying to replicate an environment that should've taken minutes with sdf deploy.
That's when it really clicked — most teams were version-controlling their files, not their projects.
What Most Teams Get Wrong
If your repo only contains `FileCabinet > SuiteScripts`, you're tracking logic without context. When you exclude your XML objects, you're leaving behind the configurations that make those scripts actually work.
⚠️
WITHOUT XML OBJECTS, YOU'RE MISSING:
- Custom record definitions
- Script deployments and parameters
- Workflows and saved searches
- Role, permission, and form settings
Why This Matters
Without the XMLs, your project can't be redeployed or cloned into another account. It's forever stuck in "manual mode."
If you've ever joined a team and heard, "Oh, don't worry, it's already in the account," you know what I mean.
Version control should represent your
entire project state — both code and configuration. Otherwise, your repo becomes "works on my account" as a service.
A proper SDF (SuiteCloud Development Framework) setup ensures you can:
- Rebuild your environment with `sdf deploy`
- Set up CI/CD for automated deployments
- Review config-level changes in your commits
How To Do It Right
Here’s how a well-structured NetSuite project should look:
📦 MySuiteAppProject
┣ 📂 FileCabinet
┃ ┣ 📂 SuiteScripts
┃ ┃ ┣ 📂 myproject ← 🟢 Always use a subfolder for your project
┃ ┃ ┃ ┣ 📂 src
┃ ┃ ┃ ┃ ┣ controllers/
┃ ┃ ┃ ┃ ┣ usecases/
┃ ┃ ┃ ┃ ┗ gateways/
┃ ┃ ┃ ┣ main.js
┃ ┃ ┃ ┗ utils/
┃ ┗ 📂 Templates
┣ 📂 Objects
┃ ┣ customrecord_mycustrecord.xml
┃ ┣ customscript_myscript.xml
┃ ┗ workflow_myworkflow.xml
┣ manifest.xml
┣ deploy.xml
┗ project.json
Tip: Always create a dedicated subfolder inside SuiteScripts (e.g., `SuiteScripts/myproject`). It keeps your files separate from other SuiteApps or scripts living in the same account. This small convention saves countless headaches later — especially when multiple projects share the same NetSuite instance.
5-Step Cleanup Process
Transform your incomplete repo into a fully deployable project in five steps:
1. Create new SDF project
Run: sdf createproject
2. Organize your scripts
Move to: FileCabinet/SuiteScripts/myproject
Add folders: controllers/, usecases/, gateways/
3. Import your configurations
Run: sdf importobjects
4. Commit everything
Scripts + XMLs + manifests + configs
5. Verify deployability
Test: sdf deploy to a sandbox account
Your repo should now represent your complete project state. This is what "deployable" actually means — not just code that runs, but a complete system that can be recreated anywhere.
Reference Projects
Want to see how we structure our SuiteScript projects?
👉 https://github.com/jonarae/suitescript-demos
You’ll find examples of:
- Clean SDF folder structure
- Organized SuiteScripts subfolders per project
- Controller-UseCase-Gateway separation
- Account Customization and SuiteApp templates
Developer Note
Your JavaScript defines what happens, but your XMLs define where and how it happens.
Leaving them out is like committing a React app without package.json.
If you’re versioning only scripts, you’re not preserving your system — just your syntax.
Treat your NetSuite project like a real software project:
structured, reproducible, and deployable.
Build Better NetSuite Projects
Proper version control is just one piece of building maintainable NetSuite applications. At ATSOURCE, we help development teams establish practices that actually scale.
Contact ATSOURCE today to learn how we can help you build NetSuite solutions that are properly structured, fully trackable, and ready to grow with your business.
Meet the Author
Jona has over a decade of experience in SuiteCloud Development on the NetSuite platform. She specializes in implementing advanced solutions and has led teams in creating high-quality software. Jona holds multiple certifications and has been recognized with awards like the Summit Award and Quality Champion Award.
Tags
Accelerate ERP Success with Expert Solutions
Ready to put what you've learned into practice? ATSOURCE delivers both the specialized talent and comprehensive NetSuite support you need to turn strategy into results.Connect with our experts today and move from planning to performance.
