lucent.json

What a Lucent package's platform code needs from the app that installs it, next to the package's package.json. The app's build merges every package's needs into .lucent/native/resolved.json, naming the package each came from. Needs that cannot all hold fail the build, naming both packages.

lucent.json

{
  "$schema": "https://lucent-lang.dev/schemas/lucent.schema.json",
  "ios": {
    "pods": { "LucentAuthKit": "~> 1.0" },
    "frameworks": ["LocalAuthentication"],
    "infoPlist": { "NSFaceIDUsageDescription": "Unlock with Face ID" }
  },
  "android": {
    "dependencies": { "androidx.biometric:biometric": "1.1.0" },
    "permissions": ["android.permission.USE_BIOMETRIC"]
  }
}

Field	Type	Meaning
ios	object	What the iOS code needs.
ios.pods	{ [key]: string }	CocoaPods the native package depends on: pod name → version requirement, as in a Podfile ("~> 1.0", ">= 1.2, < 2"). Every package's requirement on a pod goes to CocoaPods, which picks the version; requirements no version can meet fail the build. Their frameworks can be imported from lucent:ios/* once installed.
ios.frameworks	string[]	Apple frameworks the native package links, such as "CoreHaptics". Frameworks of the lucent:ios/* modules the code imports are linked without listing them here.
ios.infoPlist	{ [key]: string, boolean or string[] }	Info.plist entries: key → a string, a boolean or an array of strings. Packages must agree on a key's value, except arrays, which join. The Expo config plugin adds them: a key the app sets keeps the app's value, and an array gains the values it lacks. For bare apps, lucent build names the keys and array values the app's Info.plist lacks.
ios.nativeSources	string[]	Directories of native sources compiled into the native package's pod: C, C++, Objective-C and Swift (.h, .hpp, .m, .mm, .c, .cc, .cpp, .swift). Each directory is also a header search path. Paths are relative to the package; lucent build copies them into .lucent/native/packages/<package>/.
ios.resources	string[]	Files or directories copied into the app bundle's root under their own names, such as "assets/chime.caf". Two that would land on the same name fail the build, naming both packages: namespace one with resourceBundles.
ios.resourceBundles	{ [key]: string[] }	Resource bundles: bundle name → files or directories copied into <name>.bundle in the app. A bundle name belongs to one package.
ios.vendoredFrameworks	string[]	Prebuilt .framework or .xcframework directories the pod links and embeds. lucent:ios binds their modules (an XCFramework's through its iOS simulator slice). Two with the same framework name fail the build, naming both packages.
ios.swiftPackages	{ [key]: object }	Swift packages the pod depends on: package URL → { requirement, products }. The requirement is Xcode's, such as { "kind": "upToNextMajorVersion", "minimumVersion": "1.2.0" }. Packages must agree on a URL's requirement; their products join. React Native's spm_dependency adds them at pod install.
ios.entitlements	{ [key]: string, boolean or string[] }	The app's entitlements: key → a string, a boolean or an array of strings. Packages must agree on a key's value, except arrays, which join. The Expo config plugin adds them like Info.plist entries. For bare apps, lucent build names what the app's .entitlements file lacks.
ios.deploymentTarget	string	The lowest iOS version the package runs on, such as "15.1". The pod requires the highest any package needs, and never less than React Native's minimum. CocoaPods fails an app target below it.
android	object	What the Android code needs.
android.dependencies	{ [key]: string }	Gradle artifacts: "group:artifact" → version. They become api dependencies of the native package, so lucent:android/* can import their classes. Every package's version of an artifact goes to Gradle, which picks one; a strict version ("1.0!!") that another package's excludes fails the build.
android.permissions	string[]	Android permissions for the manifest, such as "android.permission.CAMERA". Each is declared once, however many packages list it. Permissions the SDK methods you call require are added without listing them here.
android.nativeSources	string[]	Java and Kotlin source roots of the native package's Android library, such as "native/android". Their C and C++ files (.c, .cc, .cpp) are compiled with the runtime. Each directory is also a header search path. Kotlin sources apply the Kotlin Android plugin.
android.resources	string[]	Android resource directories (the res layout: drawable/, values/…). A file-based resource two packages both have fails the build, naming both; Android's resource merger reports duplicate value resources.
android.assets	string[]	Asset directories, packaged into the app's assets. Two files with the same path fail the build, naming both packages.
android.libraries	string[]	Prebuilt .aar or .jar files, api dependencies of the native package's library. lucent:android binds their classes, before the app's Gradle build has run. Two with the same file name fail the build, naming both packages.
android.nativeLibraries	string[]	Directories of prebuilt native libraries by ABI (arm64-v8a/liborbit.so), packaged into the app. Two with the same path fail the build, naming both packages.
android.components	object[]	Components for the library's manifest, which Android merges into the app's: services, receivers, activities and providers. A class is declared once; packages that declare it differently fail the build, naming both.
android.minSdk	integer	The lowest Android API level the package runs on. The library requires the highest any package needs, and never less than the app's minSdkVersion. Android's manifest merger fails an app below it.
extensions	{ [key]: object }	Extension name → a native extension, imported as lucent:ext/<name>. A name belongs to one package of the app.

Only packages have a lucent.json: an app's own is not read. An app adds its pods, Gradle dependencies, permissions and Info.plist entries the usual way. Its pods and Gradle dependencies can be imported from lucent:ios/* and lucent:android/* too.

The schema ships in the package, at @lucent-lang/lucent/schemas/lucent.schema.json, and this table is generated from it.