Managing Modules

Managing Modules

Add, Update, Validate, and Remove operate on packages identified by .supernote-module.json. Commit the parent plugin before lifecycle operations so you can inspect and restore changes independently of transaction recovery.

Validate

Check generated files, metadata, parent integration, exports, and the local node_modules link:

supernote-module validate local-math

Add the parent Android assemble task:

supernote-module validate local-math --build --verbose

--build invokes android/gradlew :app:assembleDebug to compile-check generated integration. It does not replace the existing plugin's established workflow.

Validate everything managed by the generator:

supernote-module validate --all

Update

Warning: Update has no dry-run or file-by-file diff. Commit first.

supernote-module update local-math

Interactive Update shows a coarse replace/preserve plan and Git status. --yes accepts that plan. Update cannot change type, package name, JavaScript name, Android namespace, or package version.

Preserved source

Type	Preserved by Update
Native	Kotlin/Java below android/src/main/java/ and migrated legacy android/src/main/kotlin/, except generated packages
JNI/JSI	Complete android/src/main/cpp/ tree, including deliberately deleted starter files

Native Update retains the previous index.d.ts until the Android/KSP build regenerates it. Build after changing exports.

Replaceable files

Update may replace:

• .supernote-module.json, generated README.md, .gitignore, and package metadata;
• index.js, generated declarations, and react-native.config.js;
• Android manifest, Gradle, CMake, annotation/processor, loader, bridge, registration, and generated Kotlin/C++;
• managed Native registration in parent Android settings;
• parent dependency/link state when refresh is needed.

Keep project notes in the parent plugin, not the generated README.

Remove

Warning: Remove deletes the complete module directory, including all preserved implementation source. Commit or copy it first.

supernote-module remove local-math

Interactive removal requires typing the exact package name. Automation requires an explicit target and confirmation:

supernote-module remove local-math --yes
supernote-module remove --all --yes

Remove detaches the dependency and Native Gradle integration, refreshes dependencies unless skipped, verifies detachment, then commits deletion. A failure before commit attempts rollback.

Package-manager effects

Add normally links the local dependency. Update refreshes dependencies only when metadata or the link is stale. Remove normally refreshes after detaching.

With --skip-install, run the printed recovery command, normally:

npm install

or:

yarn install

When both package-lock.json and yarn.lock exist, operations requiring dependency work need --package-manager npm or --package-manager yarn.

Interrupted operations and rollback

Mutating commands stage changes and journal affected paths. If an interruption or external dependency change cannot be fully reversed, the command exits with code 3, retains recovery data, and prints one recovery action.

1. Follow the printed action.
2. Run the generator again to allow startup recovery.
3. Do not delete .supernote-module-transaction.json or recovery storage while recovery is pending.
4. If recovery repeatedly fails, preserve the journal and inspect the reported paths before manual intervention.

Transactions reduce partial-state risk. They are not a replacement for version control and cannot restore source intentionally deleted by a successful Remove.