Skip to main content

Loading

1

Read the manifest

The app reads meta.json and config.json. Problems stop here, all reported at once.
2

Check sdkVersion

sdkVersion is checked against the app’s SDK.
3

Verify the key

The apiKey is verified with NMCrate. See Publishing.
4

Wait for approval

If permissions are declared and not yet approved, it waits at Needs approval.
5

Build the module graph

The module graph is built from the start file and, since 2.1, from every file listed in config.json background: every import resolved, every file compiled.
6

Start required expansions

New in 2.1. Expansions named in requires are started first. If one cannot be, this expansion does not start and is marked Crashed with the reason.
7

Start

The start file runs, and whatever it exports as default is started.

Hot reload

Save any file and the app rebuilds and swaps your expansion in place.
  1. onUnload runs.
  2. Everything registered through sdk is removed (see what teardown removes).
  3. The files that changed, the files importing them, and every file that uses sdk run again. Modules that did none of those keep their state.
  4. Mounted UI re-renders with the new components.
Some consequences worth knowing:
  • Module-level state in a re-run file is reset; state on a class instance goes with it. State saved with useProjectState / useGlobalState or sdk.storage, or written to the project, survives.
  • Editing meta.json re-validates and re-verifies, so a changed id or permission set takes effect immediately.
  • A rebuild that fails leaves the running version alone and reports the error, so a typo does not take your expansion down mid-edit.

What teardown removes

Everything you added through sdk is removed for you, so you never write cleanup for it:
  • Screens and UI: pages, sidebar buttons, injections, editors, creators, creator types and stages, item types and type states, settings tabs and element types, routes, home widgets, apps, panels, status items, toolbar buttons, context-menu entries, “Add element” entries.
  • Look and language: themes, CSS variables and styles, language overlays, icons.
  • Input: commands, keybindings, CLI commands, AI tools, Echo context.
  • Pipelines: exporters, importers, transforms, drop handlers, module overrides, categories, validators, visibility and export functions, blueprint categories, pieces and skins, templates, logic-editor catalog entries (in both processes), scripting targets, GUI element presets, Coder formats and linters, reload commands, sync hooks, sync-script directives, server types, SFTP hooks.
  • Runtime: interceptors, listeners, services, project watchers, timers, sockets, running background scripts, open dialogs (they resolve null), loaded texture URLs, playing audio, the undo stack.

Stopping

Disable, uninstall and app shutdown all run the same teardown as a reload, without the re-run. Uninstalling also:
  • forgets the permission grant, so reinstalling asks again
  • 2.1 deletes the expansion’s private data folder (sdk.storage.files)
  • 2.1 removes everything it added to exports, imports and sync
onUnload is for what the SDK does not know about: flushing a buffer you kept, closing something you opened. Everything registered through sdk is already handled. For a last write when the app closes, listen to app:before-quit, and keep it quick and synchronous.

When something throws

In a component. Only that spot is replaced, by a card naming the file and line with a Retry button. The rest of the app, and the rest of your expansion, keep running. In the start file or onLoad. Nothing it registered is left behind. The Expansions page marks the expansion Crashed and shows the message and location. In an event listener. Logged against your expansion; other listeners still run. In a pipeline function (2.1). An exporter, transform, importer, sync step, interceptor or similar function that the app calls is logged against your expansion and skipped; the export, sync or import continues. A call that gets no answer times out: after 30 seconds for most stages, and after 10 minutes for exporters, importers, transforms, sync hooks and sync-script directives. In an Echo context function or a module validator (2.1). Ignored for that run. Because compiled output keeps your line numbers, the file and line in these messages are the ones you wrote.

The Expansions page

Project Settings → Expansions is where a user sees all of this:

Timers and listeners

Timers you create are tracked and cleared for you, which is why a hot reload does not leave two intervals running.