Add a Module

Add a Module

Start with a Supernote plugin that already builds and works. This guide covers only what the native-module generator adds to that plugin.

1. Confirm the generator can use the plugin

Run commands from the existing plugin root. The generator requires:

PluginConfig.json
package.json
android/
android/settings.gradle       # or settings.gradle.kts

Check the generator and Native backend without changing files:

supernote-module doctor --type native

Use --type jni or --type jsi when checking a C/C++ backend.

2. Generate local-math

supernote-module

Choose Add module, then Native Module:

Prompt	Example	Generated meaning
Package name	local-math	local_modules/local-math/, dependency name, and import string
Description	leave empty	Optional local package metadata
JavaScript name	accept Math	Generated module object
Android namespace	accept com.example.math	Kotlin/Java package and generated path
Package version	accept 0.1.0	Version of the generated local package
Install the local dependency now?	Yes	Links the generated package with the existing plugin's package manager

Package name, JavaScript name, and Android namespace must be unique among generator-managed modules. Update cannot rename them or change the backend.

Equivalent non-interactive command:

supernote-module add local-math --type native --yes

3. Implement the native function

Edit the generated user-owned file:

local_modules/local-math/android/src/main/java/com/example/math/Example.kt

package com.example.math

import com.example.math.nativemodule.annotation.SupernoteExport

class Example {
  @SupernoteExport
  fun add(left: Double, right: Double): Double = left + right
}

Do not edit generated bridge, processor, registration, Gradle, or declaration files. See Generated Files and Integration for the ownership boundary.

4. Call the generated module

Use the generated package's default import in the existing plugin:

import Math from 'local-math';

const total = await Math.add(20, 22);

Native and JNI value-returning exports use Promises. JSI exports return synchronously. Export Functions lists the supported signatures and call models.

5. Validate generated integration

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

Plain Validate checks generated structure, parent integration, export scanning, and the local dependency link. --build additionally runs the existing plugin's Android :app:assembleDebug task to compile-check the generated integration.

If Add used --skip-install, link the generated package with the package manager already used by the plugin before validation:

npm install

or:

yarn install

After validation, return to the plugin's established build, installation, and debugging workflow. Those steps are intentionally documented by Supernote, not duplicated here.

Other backends

• JNI Modules uses the same generated package flow with editable C/C++ and Promise-based calls.
• JSI Modules uses editable C/C++ and synchronous calls, with additional host-runtime requirements.

Commit before Update or Remove, then read Managing Modules.