modux

CLI for packaging and installing reusable React Native screen modules. It reads a modux.config.json, copies sources into dist/, zips artifacts for sharing, and can install modules from a local registry folder or a URL into your app under modux-modules/<name>/.

Requirements

• Node.js 18 or newer
• npm (used when installing module dependencies into the host project)

Install the CLI

From this repository:

npm install
npm run build
npm link

After npm link, the modux command is available globally on your machine.

To use without linking, run commands via node dist/index.js or add a script in package.json that invokes the built binary.

Quick start

1. Create a new module

From the project directory where you want the module tree (often your app root):

modux init

You will be prompted for a module name, author, description, version, and optionally comma-separated npm dependencies (e.g. expo-image@~3.0.11). The scaffold is created at modux-modules/<name>/ (the modux-modules folder is created if needed). If modux-modules/<name> already exists, the command exits with an error and does not overwrite anything.

Each new module includes index.ts (public entry, re-exports the screen), src/screen.tsx, modux.config.json, and README.md. The generated config matches this shape (values come from your answers):

{
  "name": "splash-screen",
  "version": "1.0.0",
  "entry": "index.ts",
  "description": "Custom React Native screen module",
  "author": "Your Name",
  "dependencies": {},
  "peerDependencies": {
    "react": "*",
    "react-native": "*"
  },
  "files": ["src", "index.ts"]
}

Add more keys under dependencies by editing modux.config.json after init (e.g. "expo-image": "~3.0.11").

2. Configure the module

Add or edit modux.config.json in the module root:

| Field | Required | Description | |--------|----------|-------------| | name | Yes | Package identifier (e.g. splash-screen). | | version | Yes | Semver string (e.g. 1.0.0). | | entry | Yes | Path to the main file (often index.ts), relative to the module root. The file must exist. | | description | No | Short summary. If present, must be a non-empty string. | | author | No | Author display name (set by modux init). If present, must be a non-empty string. | | dependencies | No | NPM packages to install with the module, e.g. { "expo-image": "~3.0.11" }. Checked on modux install. | | peerDependencies | No | Packages expected in the host app, e.g. react / react-native. Also checked on modux install. | | files | No | Extra paths (files or folders) to include in the build, relative to the module root. modux.config.json and the entry file are always copied; list additional assets here. |

3. Build

From the module root:

modux build

This empties dist/, then copies:

• modux.config.json
• The entry file
• Paths listed in files
• README.md if it exists

Paths under node_modules are skipped. After the copy, any dist/node_modules is removed.

4. Publish (zip artifact)

From the module root:

modux publish

Requires a successful modux build first (dist/ must exist). Writes {name}-{version}.zip next to modux.config.json and logs a simulated registry upload.

5. Install into an app

From the host project root (e.g. your Expo app), run modux install with one of these sources:

| Source | Example | |--------|---------| | Registry name | modux install splash-screen — looks for registry/splash-screen.zip or registry/splash-screen-*.zip under the current directory | | Path to a .zip | modux install ./artifacts/splash-screen-1.0.0.zip or an absolute path | | Path to a module folder | modux install ../other-project/modux-modules/splash-screen — folder must contain modux.config.json | | file:// URL | modux install file:///Users/me/module.zip | | HTTP(S) URL to a zip | modux install https://example.com/releases/splash-screen-1.0.0.zip — downloads, then extracts |

The install destination is always:

./modux-modules/<name>/

where <name> comes from the module’s modux.config.json (not from the zip filename).

Registry resolution (when the argument is not an existing path or URL):

• Prefer registry/<name>.zip
• Otherwise the last lexicographically sorted match for registry/<name>-*.zip

The tool reads the module’s modux.config.json, compares dependencies / peerDependencies to the host’s package.json, and may prompt:

Install required dependencies?

If you confirm, it runs npm install in the host project directory for anything still missing (using version ranges from the config when needed). The prompt also shows the latest npm version for each package when lookup succeeds.

GitHub release URLs and private repos

For URLs like https://github.com/owner/repo/releases/download/<tag>/<asset>.zip, a 404 on private repositories often means the browser link cannot be fetched anonymously. Set one of GH_TOKEN, GITHUB_TOKEN, or MODUX_GITHUB_TOKEN to a personal access token with access to that repo. The CLI can then resolve the release via the GitHub API and download the asset. For other GitHub URLs (e.g. raw files), the same token may be sent when the host is github.com.

Commands

| Command | Description | |---------|-------------| | modux init | Interactive scaffold: modux-modules/<name>/ with config, index.ts, src/screen.tsx, and README. | | modux build | Copy configured files into dist/ (from the module directory). | | modux publish | Zip dist/ to {name}-{version}.zip in the module directory; simulates upload. | | modux install <source> | Install from registry name, local .zip, module folder, file://, or HTTP(S) zip URL → modux-modules/<name>/. | | modux --help | Show help. | | modux --version | Show CLI version. |

Development

npm install
npm run build    # compile TypeScript to dist/
npm run clean    # remove dist/

License

MIT