{"id":20380524,"url":"https://github.com/tobua/numic","last_synced_at":"2025-10-23T23:11:19.687Z","repository":{"id":38890994,"uuid":"504946394","full_name":"tobua/numic","owner":"tobua","description":"React Native projects without any native code in the repository.","archived":false,"fork":false,"pushed_at":"2025-08-15T17:32:16.000Z","size":3079,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-17T22:54:34.013Z","etag":null,"topics":["react-native"],"latest_commit_sha":null,"homepage":"https://numic.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tobua.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-06-18T20:41:06.000Z","updated_at":"2025-08-15T16:24:11.000Z","dependencies_parsed_at":"2023-02-14T17:15:23.873Z","dependency_job_id":"de2e330e-b87a-4756-9ab9-6e6e11d5b3b2","html_url":"https://github.com/tobua/numic","commit_stats":{"total_commits":40,"total_committers":1,"mean_commits":40.0,"dds":0.0,"last_synced_commit":"b2525cf5a5bfdf7b61319d0c280039ac7a820385"},"previous_names":[],"tags_count":86,"template":false,"template_full_name":null,"purl":"pkg:github/tobua/numic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobua%2Fnumic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobua%2Fnumic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobua%2Fnumic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobua%2Fnumic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tobua","download_url":"https://codeload.github.com/tobua/numic/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobua%2Fnumic/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280706846,"owners_count":26376995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-23T02:00:06.710Z","response_time":142,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["react-native"],"created_at":"2024-11-15T02:07:41.356Z","updated_at":"2025-10-23T23:11:19.682Z","avatar_url":"https://github.com/tobua.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# numic\n\n\u003cimg align=\"right\" src=\"https://github.com/tobua/numic/raw/main/logo.png\" width=\"20%\" alt=\"Numic Logo\" /\u003e\n\nUtility to manage React Native projects. Commit only the changes made to native code inside `/ios` and `/android` as small patches.\n\n- Fully managed native code through Patches and Plugins\n- Runs during project installation\n- Easily upgrade native code\n- ESLint, Prettier and TypeScript configurations\n- Plugins to apply common native changes automatically\n\n## Installation\n\nRun the following in your React Native project and it will automatically add the necessary configurations and commands to your `package.json`.\n\n```sh\nbun install numic -D # Make sure to also add it manually as a trusted dependency: \"trustedDependencies\": [ \"numic\" ]\n```\n\nThis will also create fresh `/android` and `/ios` native folders and generate a patch if any changes are found. See [Migration of an Existing Project](#migration-of-an-existing-project) for more details. When **starting from scratch** the following will setup a React Native TypeScript installation with numic preinstalled and much of the default bloat removed.\n\n```sh\nbun create now numic ./my-basic-app # Basic default template with tests.\nbun create now numic ./my-app app # Tempalte with navigation, data, responsive and styles.\n```\n\nThis will prompt for an app name that can only contain **alphanumeric** characters and will be used as the initial bundle identifier. Using `NumicApp` as the name will result in `com.numicapp` as the bundle identifier. The name as well as the display name can later be configured in `app.json`.\n\n\u003e [!IMPORTANT]  \n\u003e This project follows an always up-to-date policy. Make sure to migrate to the newest React Native version when upgrading.\n\n## Commands\n\nThis framework provides the following commands that will be added to `scripts` in `package.json` upon installation.\n\n### `numic` - `bun start`\n\nShortcut command that will promt for the commands below as well as specific options for each command. This command also includes a `Distribute` option to bundle the app for Android, see [RELEASE.md](documentation/RELEASE.md).\n\n### `numic ios` - `bun ios`\n\nRun native application on iOS device or Simulator. Updates patch and pods first. Alias for `react-native run-ios` where any additional arguments are passed as well.\n\n### `numic android` - `bun android`\n\nRun native application on Android device or Emulator. Updates patch first. Alias for `react-native run-android` where any additional arguments are passed as well.\n\n### `numic lint` - `bun lint`\n\nLints and formats the whole project.\n\n\u003cdetails\u003e\n  \u003csummary\u003eLifecycle methods (automatically run during installation and when building the native application).\u003c/summary\u003e\n  \n### `numic native`\n\nGenerate or recreate native `/ios` and `/android` folders. Use this command to upgrade the native code. This also runs during project installation. Use the `--debug` flag to print template generation output, the `--version 0.X.Y` flag to override use of the installed React Native version to generate the template or the `--appName MyApp` flag to specify the name with which the template is generated.\n\n### `numic patch`\n\nCreate or updated patches from changes made to native folders.\n\n### `numic apply`\n\nApply patches from `/patch` folder to native folders.\n\n### `numic plugin`\n\nApply installed plugins.\n\n\u003c/details\u003e\n\n## Plugins\n\nIn order to automate common changes to native folders, reusable plugins can be installed. Any node_module ending in `-numic-plugin` will be treated as such and automatically installed. The previously separate [icon-numic-plugin](https://npmjs.com/icon-numic-plugin) and [android-sdk-numic-plugin](https://npmjs.com/android-sdk-numic-plugin) are now built into numic but can still be used as a reference on how to create plugins.\n\nBuilt in plugins:\n\n- `android-sdk`: Checks which Android SDK versions are installed and adapts Gradle configuration to ensure a successful build.\n  - [README in plugin/android-sdk](https://github.com/tobua/numic/blob/main/plugin/android-sdk/README.md)\n- `icon`: Creates icons in various sizes for Android and iOS.\n  - [README in plugin/icon](https://github.com/tobua/numic/blob/main/plugin/icon/README.md)\n\n### Anatomy of a Plugin\n\n```ts\nimport { join } from 'path'\n\ninterface PluginInput {\n  // Root project path.\n  projectPath?: string\n  // Location of /android or /ios folders, either root or inside /.numic.\n  nativePath?: string\n  log?: (message: string, type?: 'error' | 'warning') =\u003e void\n  options: Options\n  // Currently installed React Native version.\n  version?: string\n}\n\nexport default async ({\n  projectPath = process.cwd(),\n  nativePath = process.cwd(),\n  log = console.log,\n  options = {},\n  version,\n}: PluginInput) =\u003e {\n  const androidFolder = join(nativePath, 'android')\n  const iosFolder = join(nativePath, 'ios')\n  const appJsonPath = join(projectPath, 'app.json')\n\n  // Do something with ios and android folders.\n}\n```\n\nAny plugins placed as `.js` files inside `/plugin` or installed node_modules ending in `-numic-plugin` will automatically be run before patches are created or the app is run.\n\n## Configuration\n\nAdding a `numic` property allows to configure script and plugin behaviour. This is useful for npm plugins but also works for local plugins inside the `/plugin` folder.\n\n```js\n{\n  \"name\": \"my-app\",\n  \"numic\": {\n    \"my-plugin.js\": {\n      \"icon\": \"asset/my-icon.png\"\n    },\n    // Entries to be added to native .gitignore (changes will not appear in patch).\n    \"nativeGitignore\": [\n      \"android/app/upload-keystore.jks\",\n      \"project.pbxproj\",\n      \"!IDEWorkspaceChecks.plist\" // Include file.\n    ],\n    // Set Android Version (versionCode \u0026 versionName) in /app/build.gradle.\n    \"androidVersion\": 45,\n    \"androidVersion\": [8, \"2.31\"],\n    // Customize the Bundle ID and display name for iOS and Android.\n    \"bundleId\": \"com.tobua.numic\",\n    \"displayName\": \"num'ic\",\n    // Switch back to use the old React Native architecture.\n    \"oldArchitecture\": true,\n    // XCode customizations.\n    \"xcode\": {\n      \"developmentTeam\": \"123-456-789\", // Automatically read from system distribution certificate if missing.\n      \"category\": \"public.app-category.productivity\",\n      \"displayName\": \"My App\"\n    },\n    \"launchscreen\": {\n      \"background\": \"#FFFFFF\",\n      \"title\": \"Hello World\",\n      \"titleColor\": \"#000000\",\n      \"subtitle\": \"year\",\n      \"subtitleColor\": \"#EFEFEF\"\n    },\n    // Plugins with separate documentations.\n    \"icon\": {\n      \"icon\": \"image/icon/app-icon.png\"\n    },\n    \"android-sdk\": {\n      \"minSdkVersion\": 24,\n      \"ndkVersion\": false\n    },\n  },\n  // Will be merged with tsconfig, that's by default gitignored.\n  \"tsconfig\": {\n    \"compilerOptions\": {\n      \"skipLibCheck\": false,\n      \"include\": [\"global.d.ts\"],\n      \"target\": \"esnext\"\n    }\n  }\n}\n```\n\n## Acknowledgements\n\nThe approach to create patches using git was inspired by [patch-package](https://npmjs.com/patch-package).\n\n## Lifecycle\n\nUpon installation a new React Native template is checked out and the native `/android` and `/ios` folders are duplicated. Once for the user to make edits in the root folder and once inside `.numic` as a separate emtpy git repository. Upon installation existing plugins and patches are applied to both locations.\n\nBefore running the native application using `numic ios` or `numic android` eventual changes to native folders will be added to the patch and newly installed plugins are applied as well.\n\n## Migration of an Existing Project\n\nNative files are generated using the React Native version specified in `package.json`. To ensure a more seamless migration make sure files in your native folders are up to date with native files generated by the currently installed version. Ensure all open changes (especially inside native folders) have been committed.\n\nThe first step to start the migration is to install numic as described above. This will remove the existing native folders along with changes made. To regain those changes use git to reset changes missing in the native folders. Make sure to temporarly remove the native folders that have been added to `.gitignore`. Usually, the number of files affected is manageable and best reset one-by-one in a graphical tool like SourceTree. Once all changes are applied again a patch can be created running `numic ios` or `numic android`. Both should successfully build and run the application and all the changes made to native folders before should now be found in the `patch/current.patch` file. The only thing left is to commit the patch file along with removing the native folders from the repository source code as described below.\n\n```\n# Make sure /android and /ios do not contain any local modifications.\ngit rm -r android\ngit rm -r ios\n# Optional: automatically generated during install.\ngit rm tsconfig.json\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobua%2Fnumic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftobua%2Fnumic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobua%2Fnumic/lists"}