Implementation Guide

How to Move from SuiteBundler to SDF in NetSuite

A practical, step-by-step guide that turns the comparison into a real migration — inventory the bundles, set up the SuiteCloud SDK, create the project, import objects, manage dependencies, then deploy safely — with links to the official NetSuite documentation so you can verify everything for yourself.

Practical developer guide · Backed by the official NetSuite Help Center

Chief Technology Officer · 3x NetSuite Certified
Updated 8 min read
Back to the main article

This is the practical companion to our SDF vs SuiteBundler guide. The main article explains the two deployment models and how to choose; this page is the plain checklist for actually moving a customization off SuiteBundler and onto SDF. Work through the steps in order — inventory first, deploy sandbox-first — and use the official NetSuite documentation link under every step to confirm the exact command and behavior as you go.

Before you start — prerequisites

  • A sandbox: do the whole migration in a Sandbox or Release Preview account first — never straight to Production.
  • SDF enabled + Developer role: confirm SuiteCloud Development Framework is enabled and your role has the SDF/Developer permissions and token-based authentication.
  • Source control: have a Git repo ready — the whole point of SDF is that your project is text files you can version.

What you'll set up

  1. Inventory your bundles and choose a project type
  2. Set up the SuiteCloud SDK and Developer role
  3. Authenticate and create your SuiteCloud project
  4. Import objects, scripts and files
  5. Manage dependencies in the manifest
  6. Validate against the target account
  7. Deploy sandbox-first and roll out
1

Inventory your bundles and choose a project type

You can’t migrate what you haven’t measured. List the bundles and customizations in scope, then pick the project type — this choice is hard to undo later.

Decide:  Account Customization Project (own accounts) vs SuiteApp (distribution)
  1. List every bundle and the objects, scripts, and files it contains; flag what is genuinely in scope.
  2. Choose an ACP for accounts you own, or a SuiteApp project if you distribute to others — remember an ACP cannot be uninstalled.
  3. Confirm each object type is supported by SDF before committing to the approach.
NetSuite docs Moving from SuiteBundler to SDF SuiteCloud Project Types
2

Set up the SuiteCloud SDK and Developer role

SDF runs from your machine, not the browser. Install the tooling and make sure your role and account are ready for it.

Install:  SuiteCloud CLI for Node.js or the VS Code / WebStorm extension
  1. Install the SuiteCloud SDK — the CLI for Node.js (or Java) and/or the SuiteCloud extension for VS Code or WebStorm.
  2. Assign the Developer role (don’t default to Administrator) and confirm SDF is enabled on the account.
  3. Verify the toolchain (Node.js version, CLI install) so suitecloud commands run cleanly.
NetSuite docs SuiteCloud SDK Overview Getting Started with SDF
3

Authenticate and create your SuiteCloud project

Connect the SDK to your account with tokens, then scaffold the project that will hold your migrated customizations.

Code:  suitecloud account:setup & suitecloud project:create
  1. Set up token-based authentication to the target account with suitecloud account:setup.
  2. Scaffold the project with suitecloud project:create, choosing the ACP or SuiteApp type from Step 1.
  3. Initialize Git in the project folder so every change from here is versioned.
NetSuite docs SuiteCloud CLI for Node.js SDF Tutorial
4

Import objects, scripts and files

Pull your existing customizations into the project as XML and File Cabinet contents. You can also convert an installed bundle to an ACP zip as a starting point.

Code:  suitecloud object:import & file:import
  1. Import custom objects (records, forms, workflows, scripts) into src/Objects as XML with object:import.
  2. Import SuiteScript files and templates into src/FileCabinet with file:import.
  3. Keep the project zip small — it’s capped at 50 MB, so keep large files in the File Cabinet, not the project.
NetSuite docs Account Customization Projects SDF Architecture
5

Manage dependencies in the manifest

SDF won’t deploy if it can’t resolve what your objects depend on. Declare those dependencies in manifest.xml so deployment is clean and predictable.

File:  manifest.xml — account & SuiteApp dependencies
  1. Add references your objects rely on to manifest.xml — the IDE can add new dependencies for you (Add Dependency References to Manifest).
  2. Declare dependencies on objects from other SuiteApps or bundles that live outside your project.
  3. Re-run after each import so the manifest stays in sync with what the project actually references.
NetSuite docs Defining Dependencies on SDF Objects SuiteCloud Development Framework
6

Validate against the target account

SDF can check the whole project against the account before deploying. Use it — it surfaces conflicts and missing dependencies while they’re still cheap to fix.

Code:  suitecloud project:validate --server
  1. Run a server-side validation to compare project components against the target account and list differences or conflicts.
  2. Resolve any missing dependencies or unsupported objects the validator reports.
  3. Read the errors carefully — SDF messages can be verbose, but they point at the real blocker.
NetSuite docs SDF Architecture & Validation CLI Commands Reference
7

Deploy sandbox-first and roll out

Migration risk is deployment risk. Prove the project in Sandbox, watch for the bundle-duplication trap, then promote to Production with a rollback ready.

Process:  Sandbox deploy → verify → Production (with rollback)
  1. Deploy to Sandbox with suitecloud project:deploy and confirm objects, scripts, and form layouts land correctly.
  2. Watch for the duplication trap — deploying a SuiteApp project where the equivalent bundle is still installed flags every shared object as a duplicate.
  3. Promote to Production deliberately, keeping the prior state ready as a rollback.
NetSuite docs SuiteCloud Development Framework Moving from SuiteBundler to SDF

A note on accuracy: SuiteCloud CLI commands, supported object types, and tooling names evolve between releases (the SDK has gained capabilities every NetSuite version). Always confirm each command and the supported-objects list against its official reference, and validate the project in Sandbox before deploying to Production.

Official NetSuite documentation

Every step links to the source. Full help center: NetSuite Applications Suite — Online Help.

Where a lift-and-shift ends and engineering begins

Everything above gets your customizations off SuiteBundler and into a version-controlled SDF project. What sits beyond a mechanical move — restructuring objects into clean SuiteApp boundaries, wiring the project into a CI/CD pipeline, handling unsupported object types, and planning a client cutover that avoids duplication errors — is engineering work. It often means re-architecting the package and adding automated validation, not just importing XML.

A migration touches live, distributed customizations, so build in a Sandbox, validate against the target before every deploy, and keep a rollback. For the full reasoning behind each decision — the two models, the project types, and when to keep using Bundler — read the companion guide.

Back to the main article
Migrating off SuiteBundler? Our NetSuite engineers inventory your bundle estate, rebuild it as a version-controlled SDF project with clean dependencies, and roll out Sandbox-first — so nothing breaks for you or your clients.
Talk to a NetSuite deployment engineer

Documentation links point to the official Oracle NetSuite Help Center (docs.oracle.com). Exact commands, menu paths, and supported object types vary by NetSuite version and edition — confirm each step against the linked Help Center page and validate in Sandbox first.