@expo-harmony/config-plugins 55.0.10-harmony.1 → 55.0.10-harmony.3

package/README.md

@@ -2,7 +2,7 @@
 
 [**GitHub 仓库**](https://github.com/renbaoshuo/expo-harmony/tree/master/packages/config-plugins)
 
-为 Expo Config Plugins 提供 HarmonyOS 平台扩展，包括 `expo.harmony` 配置类型、Harmony Base Mods、原生工程文件与资源 Mod、路径解析及插件资源归属管理。
+这个包定义 `expo.harmony` 的字段和默认值，并提供读写 Harmony 原生工程的 Mod、资源与权限操作，以及插件生成文件的归属管理。
 
 ## 安装
 
@@ -10,9 +10,9 @@
 npm install @expo-harmony/config-plugins
 ```
 
-## 配置类型
+## 声明 HarmonyOS 配置
 
-在 `app.config.js` 中可使用 `defineExpoHarmonyConfig` 声明 HarmonyOS 配置：
+用 `defineExpoHarmonyConfig` 在 `app.config.js` 里写配置：
 
 ```js
 const { defineExpoHarmonyConfig } = require('@expo-harmony/config-plugins');
@@ -29,9 +29,40 @@ module.exports = defineExpoHarmonyConfig({
 });
 ```
 
-## 编写 HarmonyOS 配置插件
+`defineExpoHarmonyConfig` 里的 `harmony` 字段可以写这些配置：
 
-使用对应的 Mod 修改生成后的 HarmonyOS 原生配置。例如，向 `module.json5` 添加信息：
+| 字段 | 默认值 / 说明 |
+| --- | --- |
+| `bundleName` | 必填，至少三段点分隔的合法标识符 |
+| `moduleName` | `entry` |
+| `abilityName` | `EntryAbility` |
+| `productName` | `default` |
+| `vendor` | `expo-harmony` |
+| `versionCode` | `1` |
+| `versionName` | 配置里的 `version`，没有则 `1.0.0` |
+| `targetApiVersion` | `24` |
+| `targetSdkVersion` | 数字或 SDK 标签，默认跟随 `targetApiVersion` |
+| `compatibleSdkVersion` | `13`，不能低于 13，也不能大于 `targetApiVersion` |
+| `deviceTypes` | `['phone', 'tablet']` |
+| `permissions` | 权限列表，默认包含 `ohos.permission.INTERNET` |
+| `skills` | 技能列表，`scheme` 会追加对应项 |
+| `querySchemes` | 默认包含 `http`、`https`、`tel`、`sms` 和 `scheme` |
+| `icon` | 配置里的 `icon` |
+| `label` | 配置里的 `name` |
+| `backgroundColor` | 配置里的 `backgroundColor`，没有则 `#FFFFFF` |
+| `orientation` | 配置里的 `orientation`，没有则 `default` |
+| `userInterfaceStyle` | 供 `expo-system-ui` 和 `expo-splash-screen` 插件读取的 HarmonyOS 外观覆盖值，由模块插件校验和应用 |
+| `jsEngine` | `hermes` |
+| `abiFilters` | `['arm64-v8a', 'x86_64']` |
+| `signingConfigFile` | 签名配置文件路径，不设置则忽略 |
+
+`targetSdkVersion` 和 `compatibleSdkVersion` 可以写数字或带 API 级别的 SDK 标签。内置标签覆盖 API 13、14、20、21、23、24，其他版本写成 `6.1.1(24)` 这样的形式。`backgroundColor` 写 `#RRGGBB` 或 `#RRGGBBAA`，写入原生工程时转成 ARGB。`jsEngine` 目前只能是 `hermes`。
+
+`normalizeHarmonyConfig(config)` 返回补齐默认值并校验后的配置。
+
+## 修改原生工程文件
+
+Mod 读写原生工程里的文件。以 `module.json5` 为例：
 
 ```js
 const { withModuleJson } = require('@expo-harmony/config-plugins');
@@ -39,9 +70,7 @@ const { withModuleJson } = require('@expo-harmony/config-plugins');
 module.exports = function withExampleMetadata(config) {
   return withModuleJson(config, (mod) => {
     const moduleConfig = mod.modResults.module || {};
-    const metadata = Array.isArray(moduleConfig.metadata)
-      ? moduleConfig.metadata
-      : [];
+    const metadata = Array.isArray(moduleConfig.metadata) ? moduleConfig.metadata : [];
 
     mod.modResults.module = {
       ...moduleConfig,
@@ -52,13 +81,176 @@ module.exports = function withExampleMetadata(config) {
 };
 ```
 
-包内提供 JSON、文本、资源、自动链接等 Harmony Mod。常用入口包括 `withModuleJson`、`withAppJson`、`withStrings`、`withColors`、`withMedia`、`withCMakeLists`、`withHarmonyDangerousMod` 等，可以在 export 中查看完整列表。
+回调在 `mod.modResults` 上读写并返回 `mod`。JSON 文件的 `modResults` 是对象，文本文件是字符串，返回结果写回文件。同一个 Mod 注册多次时，后注册的回调先执行。需要读最终原始配置时用 `mod.modRawConfig`。
+
+内置 Mod 与目标文件：
+
+| 接口                       | 文件                                                                                                          |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `withAppJson`              | `AppScope/app.json5`                                                                                          |
+| `withProjectBuildProfile`  | `build-profile.json5`                                                                                         |
+| `withRootOhPackage`        | `oh-package.json5`                                                                                            |
+| `withHvigorConfig`         | `hvigor/hvigor-config.json5`                                                                                  |
+| `withEntryBuildProfile`    | `entry/build-profile.json5`                                                                                   |
+| `withEntryOhPackage`       | `entry/oh-package.json5`                                                                                      |
+| `withModuleJson`           | `entry/src/main/module.json5`                                                                                 |
+| `withProfiles`             | `entry/src/main/resources/base/profile/main_pages.json`                                                       |
+| `withReactNativeConfig`    | `react-native.config.js`                                                                                      |
+| `withRootHvigor`           | `hvigorfile.ts`                                                                                               |
+| `withEntryHvigor`          | `entry/hvigorfile.ts`                                                                                         |
+| `withEntryAbility`         | `entry/src/main/ets/entryability/EntryAbility.ets`                                                            |
+| `withIndexPage`            | `entry/src/main/ets/pages/Index.ets`                                                                          |
+| `withWorker`               | `entry/src/main/ets/workers/RNOHWorker.ets`                                                                   |
+| `withArkTSPackageProvider` | `entry/src/main/ets/PackageProvider.ets`                                                                      |
+| `withCppPackageProvider`   | `entry/src/main/cpp/PackageProvider.cpp`                                                                      |
+| `withCMakeLists`           | `entry/src/main/cpp/CMakeLists.txt`                                                                           |
+| `withStrings`              | `AppScope/resources/base/element/string.json`、`entry/src/main/resources/base/element/string.json`            |
+| `withColors`               | `entry/src/main/resources/base/element/color.json`、`entry/src/main/resources/dark/element/color.json`        |
+| `withMedia`                | `AppScope/resources/base/media`、`entry/src/main/resources/base/media`、`entry/src/main/resources/dark/media` |
+
+`withHarmonyMod(config, [name, action])` 按名称注册 Mod，`HARMONY_MOD_NAMES` 列出可用名称。`withHarmonyResources` 把同一个 action 注册到 strings、colors、media。`withHarmonyDangerousMod` 用来改写没有固定目标文件的内容。`withHarmonyAutolinking` 执行原生模块自动链接。`withHarmonyBaseMods` 注册整套 Harmony Base Mod。
+
+`compileHarmonyModsAsync(config, { projectRoot, introspect?, ignoreExistingNativeFiles? })` 直接执行 Mods。`introspect: true` 时只跑静态 Mod，不写文件，结果保存在 `_internal.modResults.harmony`，自定义文件以 `file:<相对路径>` 为键。从 `expo/config` 读配置时要设 `isModdedConfig: true`，否则 Mods 会丢失。
+
+`HarmonyPaths` 提供工程内路径常量（`HARMONY_PATHS`、`PROJECT_PATHS`、`PROJECT_PATH_CANDIDATES`、`RESOURCE_PATHS`）和路径解析、边界检查函数。
+
+## Manifest
+
+`HarmonyManifest` 原地修改和查询 `module.json5`：
+
+- `getModuleOrThrow(manifest)` 读取 `module`，缺失或格式不对时抛错。
+- `getMainAbilityOrThrow(manifest, name?)` 按显式名称、`mainElement`、第一个 Ability 的顺序选取，目标缺失或重名时抛错。
+- `setMetadata(target, item)`、`removeMetadata(target, name)` 按名称更新 module 或 Ability 的 metadata，保留其他条目和字段。
+- `ensureExtensionAbility(manifest, ability)` 添加 ExtensionAbility，重复调用不会追加，同名声明存在不兼容字段时抛错。
+
+`withModuleJson` 的结果是 `HarmonyModuleJson`。`HarmonyModule`、`HarmonyAbility`、`HarmonyExtensionAbility`、`HarmonyMetadata` 保留未知字段，可以使用新 SDK 的字段。`HarmonySkillUri` 的值可以是字符串、数字或布尔值。
+
+```js
+const { HarmonyManifest, withModuleJson } = require('@expo-harmony/config-plugins');
+
+function withExample(config) {
+  return withModuleJson(config, (mod) => {
+    const module = HarmonyManifest.getModuleOrThrow(mod.modResults);
+    HarmonyManifest.setMetadata(module, { name: 'example.enabled', value: 'true' });
+
+    const ability = HarmonyManifest.getMainAbilityOrThrow(mod.modResults);
+    ability.backgroundModes = [...new Set([...(ability.backgroundModes || []), 'audioPlayback'])];
+    return mod;
+  });
+}
+```
+
+## 权限
+
+`withHarmonyPermissions(config, permissions)` 把权限合并进 `expo.harmony.permissions` 和生成的 `module.json5`。权限名用完整的 `ohos.permission.*`。同名权限合并 `usedScene.abilities`，任一声明要求 `always` 就保留 `always`，后传入的 `reason` 覆盖旧值。`reason` 写 `$string:...` 这样的原生引用，文案放在字符串资源里。
+
+`HarmonyPermissions.mergePermissions(current, additions)` 返回合并后的新数组。`ensurePermissions(manifest, additions)` 和 `removePermissions(manifest, names)` 修改并返回 manifest。删除只改应用 manifest 里列出的声明，不会动 HAR 自己声明的权限。
+
+## 字符串、颜色和媒体
+
+`HarmonyResources.setString(file, { name, value })`、`removeString(file, name)`、`setColor`、`removeColor` 原地修改单个资源 JSON 对象并返回，按名称去重，保留其他内容。空字符串是合法值，删除要显式调用 remove。
+
+```js
+const { HarmonyResources, registerHarmonyConfigPlugin, withStrings } = require('@expo-harmony/config-plugins');
+
+function withExampleReason(config, reason) {
+  config = registerHarmonyConfigPlugin(config, 'example-plugin', {
+    resources: { strings: { entry: ['example_permission_reason'] } },
+  });
+  return withStrings(config, (mod) => {
+    const entry = (mod.modResults.entry ??= {});
+    HarmonyResources.setString(entry, { name: 'example_permission_reason', value: reason });
+    return mod;
+  });
+}
+```
+
+`setColor` 接收原生颜色值，不改通道顺序。`HarmonyResources.toArgb` 把 `#RRGGBB`、Expo 的 `#RRGGBBAA` 或无符号 RGBA 整数转成 Harmony 颜色。命名颜色先用调用方的颜色解析器转成 RGBA 整数。
+
+`withStrings` 改的是 `app` 和 `entry`，`withColors` 改的是 `entry` 和 `entryDark`。`withMedia` 在 `app`、`entry` 或 `entryDark` 里按文件名设置 `{ source }` 或 `{ content }`，`replaceBase: true` 会替换同基本名的其他扩展名。
+
+## Rawfile 和生成文件
+
+```js
+const { withRawfile, withHarmonyGeneratedFiles } = require('@expo-harmony/config-plugins');
+
+function withExampleFiles(config) {
+  config = withRawfile(config, {
+    owner: 'example-plugin',
+    files: {
+      'audio/example.wav': { source: './assets/example.wav' },
+      'example.json': { content: JSON.stringify({ enabled: true }) },
+    },
+  });
+  return withHarmonyGeneratedFiles(config, {
+    owner: 'example-plugin',
+    files: {
+      'entry/src/main/ets/example/Example.ets': { content: 'export const enabled = true;\n' },
+    },
+  });
+}
+```
+
+`withRawfile` 的路径相对 `entry/src/main/resources/rawfile`，`withHarmonyGeneratedFiles` 的路径相对 Harmony 工程根目录。路径用 `/`，不接受绝对路径、`.`、`..` 和指向工程外的符号链接。`source` 相对 Expo 项目根目录，也可以用绝对路径；`content` 是字符串或 `Uint8Array`，和 `source` 二选一。
+
+两个接口会覆盖自己声明的目标文件，执行时读取源文件，先校验整批输入再原子写入，并登记文件归属。introspection 阶段不写文件。多个插件不能声明同一个目标路径，同一个 owner 的多次调用合并成这次配置的完整文件集合。
+
+配合 `@expo-harmony/prebuild-config` 时，下次生成会清掉同一 owner 不再声明的旧文件，卸载插件会清理它管理的文件。字体这类需要动态计算的场景可以用 `withHarmonyDangerousMod`、`atomicWrite` 和 `recordManagedFile`。
+
+## 自定义文件
+
+`withHarmonyJsonFile` 管理一个 JSON 或 JSON5 文件：
+
+```js
+const { withHarmonyJsonFile } = require('@expo-harmony/config-plugins');
+
+module.exports = (config) =>
+  withHarmonyJsonFile(config, {
+    path: 'entry/src/main/resources/zh_CN/element/string.json',
+    owner: 'my-library/locales',
+    action: (mod) => {
+      mod.modResults.string = [{ name: 'my_message', value: '你好' }];
+      return mod;
+    },
+  });
+```
+
+一个文件由一个 owner 管理。其他插件用相同的 `path` 和 `owner` 继续修改时，文件只读写一次；不同 owner 声明同一路径会报错。多个插件改资源数组时按名称合并，避免覆盖别人的条目。
+
+`createHarmonyFileMod({ path, owner, parse, serialize, isIntrospective? })` 用来定义其他文本格式，返回和 `withModuleJson` 一样接收 `(config, action)` 的函数。`parse` 接收文件内容或表示文件不存在的 `null`，`serialize` 返回字符串，两者是纯函数。序列化对象时可以用 `stableHarmonyJson`，它按固定键序输出。定义一次并导出，供其他插件复用。只有静态、可 JSON 序列化、不产生文件副作用的 Mod 才能设 `isIntrospective: true`，JSON 快捷接口已经开启。
+
+provider 会校验路径、登记归属并原子写入，移除 provider 后 prebuild 会清理它生成的文件。它管理整个文件，不会单独撤销某个 action 对字段的修改。内置 Mod 已经管理的路径不能再声明。
+
+## 声明文件与资源归属
+
+`registerHarmonyConfigPlugin(config, owner, claims)` 声明插件占用的文件和资源名。`files` 是相对路径列表，`resources` 按 `strings`、`colors`、`media` 分组，每组再按作用域列出名称，`ability` 现在能写 `startWindowBackground` 和 `startWindowIcon`。不同 owner 声明同一个文件会报错。
+
+```js
+const { registerHarmonyConfigPlugin } = require('@expo-harmony/config-plugins');
+
+module.exports = (config) =>
+  registerHarmonyConfigPlugin(config, 'my-plugin', {
+    files: ['entry/src/main/resources/base/profile/shortcuts.json'],
+    resources: {
+      colors: { entry: ['brand_primary'] },
+      strings: { app: ['app_display_name'] },
+    },
+  });
+```
+
+`recordManagedFile(config, file, owner)` 单独登记一个受管理文件，适合动态生成的文件。
+
+## 插件组合
+
+`withPlugins`、`withRunOnce`、`withStaticPlugin`、`createRunOncePlugin` 可以写 `platforms: ['harmony']`，并保留调用方的配置类型。其他 Expo 通用工具从项目的 `expo/config-plugins` 取。
+
+## 类型
 
-`withHarmonyBaseMods` 负责注册所有 Harmony Base Mods，通常由 `@expo-harmony/prebuild-config` 调用，应用和第三方配置插件无需重复注册。`registerHarmonyConfigPlugin` 可声明插件拥有的资源或 Ability 字段，避免多个插件在生成阶段产生归属冲突。
+`HarmonyConfigPlugin<Props>` 保留传入配置的具体类型，可以写 `platforms: ['harmony']`。`HarmonyModAction<T>` 和 `HarmonyModConfig<T>` 里的 Harmony 配置、`modRawConfig.harmony`、`modRequest.platform: 'harmony'` 和结果都有类型。文件 Mod 还能读到可选的 `modRequest.modFile` 和 `modFileExists`。
 
 ## Author
 
 **expo-harmony** © [Baoshuo](https://github.com/renbaoshuo), Released under the MIT License.<br>
 Authored and maintained by Baoshuo with help from [contributors](https://github.com/renbaoshuo/expo-harmony/contributors).
 
-> [Personal Website](https://baoshuo.ren) · [Blog](https://blog.baoshuo.ren) · GitHub [@renbaoshuo](https://github.com/renbaoshuo) · Twitter [@baoshuo](https://twitter.com/baoshuo)
+> [Personal Website](https://baoshuo.ren) · [Blog](https://blog.baoshuo.ren) · GitHub [@renbaoshuo](https://github.com/renbaoshuo) · Twitter [@renbaoshuo](https://twitter.com/renbaoshuo)

package/build/compiler.d.ts

@@ -0,0 +1,7 @@
+import type { ExpoConfigWithHarmony } from './config';
+export interface HarmonyCompileOptions {
+    projectRoot: string;
+    introspect?: boolean;
+    ignoreExistingNativeFiles?: boolean;
+}
+export declare function compileHarmonyModsAsync<Config extends ExpoConfigWithHarmony>(config: Config, options: HarmonyCompileOptions): Promise<Config>;

package/build/compiler.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileHarmonyModsAsync = compileHarmonyModsAsync;
+const config_plugins_1 = require("@expo/config-plugins");
+const mods_1 = require("./mods");
+async function compileHarmonyModsAsync(config, options) {
+    return await (0, config_plugins_1.compileModsAsync)((0, mods_1.withHarmonyBaseMods)(config), {
+        ...options,
+        platforms: ['harmony'],
+        assertMissingModProviders: true,
+    });
+}

package/build/composition.d.ts

@@ -0,0 +1,24 @@
+import { type ConfigPlugin } from '@expo/config-plugins';
+import type { HarmonyConfigPlugin } from './pluginTypes';
+import type { ExpoConfigWithHarmony } from './config';
+type CompatiblePlugin<Props = void> = {
+    apply(config: ExpoConfigWithHarmony, props: Props): ExpoConfigWithHarmony;
+}['apply'];
+export type HarmonyPluginReference = string | CompatiblePlugin<never>;
+export type HarmonyStaticPlugin = HarmonyPluginReference | [HarmonyPluginReference, unknown];
+export declare const withPlugins: HarmonyConfigPlugin<HarmonyStaticPlugin[]>;
+export declare const withRunOnce: HarmonyConfigPlugin<{
+    plugin: CompatiblePlugin;
+    name: string;
+    version?: string;
+}>;
+export declare const withStaticPlugin: HarmonyConfigPlugin<{
+    plugin: HarmonyStaticPlugin;
+    projectRoot?: string;
+    fallback?: CompatiblePlugin<{
+        _resolverError: Error;
+    } & Record<string, unknown>>;
+}>;
+export declare function createRunOncePlugin<Props>(plugin: HarmonyConfigPlugin<Props>, name: string, version?: string): HarmonyConfigPlugin<Props>;
+export declare function createRunOncePlugin<Props>(plugin: ConfigPlugin<Props>, name: string, version?: string): HarmonyConfigPlugin<Props>;
+export {};

package/build/composition.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withStaticPlugin = exports.withRunOnce = exports.withPlugins = void 0;
+exports.createRunOncePlugin = createRunOncePlugin;
+const config_plugins_1 = require("@expo/config-plugins");
+exports.withPlugins = config_plugins_1.withPlugins;
+exports.withRunOnce = config_plugins_1.withRunOnce;
+exports.withStaticPlugin = config_plugins_1.withStaticPlugin;
+function createRunOncePlugin(plugin, name, version) {
+    return (0, config_plugins_1.createRunOncePlugin)(plugin, name, version);
+}

package/build/config.d.ts

@@ -0,0 +1,51 @@
+import type { ExpoConfig } from '@expo/config-types';
+export type HarmonyPlatform = 'harmony';
+export type ExpoKnownPlatform = NonNullable<ExpoConfig['platforms']>[number];
+export type ExpoHarmonyPlatform = ExpoKnownPlatform | HarmonyPlatform;
+export type HarmonyDeviceType = 'phone' | 'tablet' | '2in1';
+export type HarmonyOrientation = 'default' | 'portrait' | 'landscape' | 'portrait_inverted' | 'landscape_inverted' | 'auto_rotation';
+export interface HarmonyPermission {
+    name: string;
+    reason?: string;
+    usedScene?: {
+        abilities?: string[];
+        when?: 'inuse' | 'always';
+    };
+}
+export type HarmonySkillUri = Record<string, string | number | boolean>;
+export interface HarmonySkill {
+    entities?: string[];
+    actions?: string[];
+    uris?: HarmonySkillUri[];
+}
+export interface HarmonyConfig {
+    bundleName: string;
+    moduleName?: string;
+    abilityName?: string;
+    productName?: string;
+    vendor?: string;
+    versionCode?: number;
+    versionName?: string;
+    targetApiVersion?: number;
+    targetSdkVersion?: number | string;
+    compatibleSdkVersion?: number | string;
+    deviceTypes?: HarmonyDeviceType[];
+    permissions?: HarmonyPermission[];
+    skills?: HarmonySkill[];
+    querySchemes?: string[];
+    icon?: string;
+    label?: string;
+    backgroundColor?: string;
+    orientation?: HarmonyOrientation;
+    userInterfaceStyle?: 'light' | 'dark' | 'automatic';
+    jsEngine?: 'hermes';
+    abiFilters?: string[];
+    signingConfigFile?: string;
+}
+export type ExpoConfigWithHarmony = Omit<ExpoConfig, 'platforms'> & {
+    platforms?: ExpoHarmonyPlatform[];
+    harmony?: HarmonyConfig;
+};
+export declare function defineExpoHarmonyConfig<T extends {
+    expo: ExpoConfigWithHarmony;
+} | ExpoConfigWithHarmony>(config: T): T;

package/build/config.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineExpoHarmonyConfig = defineExpoHarmonyConfig;
+function defineExpoHarmonyConfig(config) {
+    return config;
+}

package/build/customFiles.d.ts

@@ -0,0 +1,15 @@
+import type { HarmonyConfigPlugin, HarmonyModAction } from './pluginTypes';
+export interface HarmonyFileModOptions<T> {
+    path: string;
+    owner: string;
+    parse: (source: string | null) => T;
+    serialize: (value: T) => string;
+    isIntrospective?: boolean;
+}
+export declare function createHarmonyFileMod<T>(options: HarmonyFileModOptions<T>): HarmonyConfigPlugin<HarmonyModAction<T>>;
+export interface HarmonyJsonFileOptions {
+    path: string;
+    owner: string;
+    action: HarmonyModAction<Record<string, unknown>>;
+}
+export declare const withHarmonyJsonFile: HarmonyConfigPlugin<HarmonyJsonFileOptions>;

package/build/customFiles.js

@@ -0,0 +1,108 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withHarmonyJsonFile = void 0;
+exports.createHarmonyFileMod = createHarmonyFileMod;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const config_plugins_1 = require("@expo/config-plugins");
+const json5_1 = __importDefault(require("json5"));
+const errors_1 = require("./errors");
+const files_1 = require("./files");
+const mods_1 = require("./mods");
+const ownership_1 = require("./ownership");
+const paths_1 = require("./paths");
+const providers = new WeakMap();
+function createHarmonyFileMod(options) {
+    const definition = Object.freeze({ ...options });
+    const { path: relative, owner, parse, serialize, isIntrospective = false } = definition;
+    (0, ownership_1.normalizeHarmonyConfigPlugins)([{ owner, files: [relative] }]);
+    const reserved = Object.values(paths_1.ManagedPaths).includes(relative)
+        || Object.values(paths_1.ResourcePaths).some(scopes => Object.values(scopes).some(file => relative === file))
+        || Object.values(paths_1.ResourcePaths.media).some(directory => relative.startsWith(`${directory}/`));
+    if (reserved || relative.split('/').some(part => part === '.git') || relative.startsWith('.expo/')) {
+        throw new errors_1.HarmonyConfigPluginError('ERR_HARMONY_PATH_INVALID', `Use the built-in mod for reserved path ${relative}.`);
+    }
+    if (typeof parse !== 'function' || typeof serialize !== 'function') {
+        throw new TypeError('A file mod requires parse and serialize functions.');
+    }
+    const name = `file:${relative}`;
+    return (config, action) => {
+        const mods = config.mods;
+        const provider = mods?.harmony?.[name];
+        if (provider) {
+            const stored = providers.get(provider);
+            if (!stored || stored.owner !== owner || stored.parse !== parse
+                || stored.serialize !== serialize || !!stored.isIntrospective !== isIntrospective) {
+                throw new errors_1.HarmonyConfigPluginError('ERR_HARMONY_CONFIG_INVALID', `Conflicting providers for ${relative}. Reuse the same file mod definition.`);
+            }
+        }
+        const claims = (0, ownership_1.getHarmonyConfigPlugins)(config).find(plugin => plugin.owner === owner);
+        (0, ownership_1.registerHarmonyConfigPlugin)(config, owner, {
+            ...claims, files: [...new Set([...(claims?.files ?? []), relative])],
+        });
+        if (!provider) {
+            const actions = [];
+            (0, config_plugins_1.withBaseMod)(config, {
+                platform: 'harmony',
+                mod: name,
+                isProvider: true,
+                isIntrospective,
+                saveToInternal: isIntrospective,
+                async action(value) {
+                    const { nextMod: _next, ...request } = value.modRequest;
+                    const file = await (0, paths_1.resolveHarmonyPath)(request.platformProjectRoot, relative);
+                    let source = null;
+                    if (!request.ignoreExistingNativeFiles) {
+                        try {
+                            source = await promises_1.default.readFile(file, 'utf8');
+                        }
+                        catch (cause) {
+                            if (cause.code !== 'ENOENT') {
+                                throw new errors_1.HarmonyConfigPluginError('ERR_HARMONY_TEXT_INVALID', `Cannot read ${file}: ${cause.message}`, { cause, file, operation: `harmony.${name}.read` });
+                            }
+                        }
+                    }
+                    let result = {
+                        ...value,
+                        modRequest: { ...request, modFile: file, modFileExists: source !== null },
+                        modResults: parse(source),
+                    };
+                    for (let index = actions.length - 1; index >= 0; index--) {
+                        result = await actions[index](result);
+                    }
+                    const output = serialize(result.modResults);
+                    if (typeof output !== 'string')
+                        throw new TypeError(`Serializer for ${relative} must return a string.`);
+                    if (!request.introspect) {
+                        await (0, files_1.atomicWrite)(file, output);
+                        (0, mods_1.recordManagedFile)(result, file, owner);
+                    }
+                    return result;
+                },
+            });
+            const table = config.mods.harmony;
+            table[name].expoHarmonyLateActions = actions;
+            providers.set(table[name], definition);
+            // CNG must fingerprint custom outputs after they have been written.
+            for (const stage of ['patch', 'manifest']) {
+                if (table[stage]) {
+                    const provider = table[stage];
+                    delete table[stage];
+                    table[stage] = provider;
+                }
+            }
+        }
+        return (0, mods_1.registerMod)(config, name, action);
+    };
+}
+function parseJson(source) {
+    const value = source === null ? {} : json5_1.default.parse(source);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TypeError('A Harmony JSON file must contain an object.');
+    }
+    return value;
+}
+const withHarmonyJsonFile = (config, { path, owner, action }) => (createHarmonyFileMod({ path, owner, parse: parseJson, serialize: files_1.stableJson, isIntrospective: true })(config, action));
+exports.withHarmonyJsonFile = withHarmonyJsonFile;

package/build/errors.d.ts

@@ -0,0 +1,11 @@
+export interface HarmonyConfigPluginErrorOptions {
+    cause?: unknown;
+    file?: string;
+    operation?: string;
+}
+export declare class HarmonyConfigPluginError extends Error {
+    readonly code: string;
+    readonly operation: string;
+    readonly file?: string;
+    constructor(code: string, message: string, options?: HarmonyConfigPluginErrorOptions);
+}

package/build/errors.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HarmonyConfigPluginError = void 0;
+class HarmonyConfigPluginError extends Error {
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'HarmonyConfigPluginError';
+        this.code = code;
+        this.operation = options.operation || 'config-plugin';
+        if (options.file)
+            this.file = options.file;
+    }
+}
+exports.HarmonyConfigPluginError = HarmonyConfigPluginError;

package/build/files.d.ts

@@ -0,0 +1,6 @@
+export declare function stableJson(value: unknown): string;
+export declare function readJson5<T>(file: string, fallback: T, name: string): Promise<T>;
+export declare function readText(file: string, fallback?: string): Promise<string>;
+export declare function atomicWrite(file: string, content: string | Uint8Array): Promise<void>;
+export declare function writeJson5(file: string, value: unknown): Promise<void>;
+export declare function sha256File(file: string): Promise<string>;

package/build/files.js

@@ -0,0 +1,69 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stableJson = stableJson;
+exports.readJson5 = readJson5;
+exports.readText = readText;
+exports.atomicWrite = atomicWrite;
+exports.writeJson5 = writeJson5;
+exports.sha256File = sha256File;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const json5_1 = __importDefault(require("json5"));
+const errors_1 = require("./errors");
+function sortValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    if (value && typeof value === 'object' && !Buffer.isBuffer(value)) {
+        const record = value;
+        const entries = Object.keys(record).sort().map(key => [key, sortValue(record[key])]);
+        return Object.fromEntries(entries);
+    }
+    return value;
+}
+function stableJson(value) {
+    return `${JSON.stringify(sortValue(value), null, 2)}\n`;
+}
+async function readJson5(file, fallback, name) {
+    try {
+        const source = await node_fs_1.default.promises.readFile(file, 'utf8');
+        return json5_1.default.parse(source);
+    }
+    catch (cause) {
+        if (cause.code === 'ENOENT')
+            return structuredClone(fallback);
+        throw new errors_1.HarmonyConfigPluginError('ERR_HARMONY_JSON5_INVALID', `Cannot parse ${file} for harmony.${name}: ${cause.message}`, { cause, file, operation: `harmony.${name}.read` });
+    }
+}
+async function readText(file, fallback = '') {
+    try {
+        return await node_fs_1.default.promises.readFile(file, 'utf8');
+    }
+    catch (cause) {
+        if (cause.code === 'ENOENT')
+            return fallback;
+        throw new errors_1.HarmonyConfigPluginError('ERR_HARMONY_TEXT_INVALID', `Cannot read ${file}: ${cause.message}`, { cause, file, operation: 'harmony.mod.read' });
+    }
+}
+async function atomicWrite(file, content) {
+    const directory = node_path_1.default.dirname(file);
+    const temporary = node_path_1.default.join(directory, `.${node_path_1.default.basename(file)}.${process.pid}.${node_crypto_1.default.randomBytes(6).toString('hex')}.tmp`);
+    await node_fs_1.default.promises.mkdir(directory, { recursive: true });
+    try {
+        await node_fs_1.default.promises.writeFile(temporary, content);
+        await node_fs_1.default.promises.rename(temporary, file);
+    }
+    finally {
+        await node_fs_1.default.promises.rm(temporary, { force: true }).catch(() => { });
+    }
+}
+async function writeJson5(file, value) {
+    await atomicWrite(file, stableJson(value));
+}
+async function sha256File(file) {
+    const data = Uint8Array.from(await node_fs_1.default.promises.readFile(file));
+    return node_crypto_1.default.createHash('sha256').update(data).digest('hex');
+}

package/build/generatedFiles.d.ts

@@ -0,0 +1,15 @@
+import type { HarmonyConfigPlugin } from './pluginTypes';
+export type HarmonyFileDescriptor = {
+    source: string;
+    content?: never;
+} | {
+    source?: never;
+    content: string | Uint8Array;
+};
+export type HarmonyFileMap = Record<string, HarmonyFileDescriptor>;
+export interface HarmonyGeneratedFilesOptions {
+    owner: string;
+    files: HarmonyFileMap;
+}
+export declare const withHarmonyGeneratedFiles: HarmonyConfigPlugin<HarmonyGeneratedFilesOptions>;
+export declare const withRawfile: HarmonyConfigPlugin<HarmonyGeneratedFilesOptions>;