expo-rotation-module 0.1.0 → 1.0.1

package/README.md

@@ -1,77 +1,173 @@
 # expo-rotation-module
 
-An Expo native module that controls the Android system rotation settings (ACCELEROMETER_ROTATION and USER_ROTATION).
+A small Expo native module that lets an Android app read and control the system rotation settings (ACCELEROMETER_ROTATION and USER_ROTATION) and request the `WRITE_SETTINGS` permission.
 
-## Overview
-This package exposes a small API to check and request the WRITE_SETTINGS permission and to read/set the global rotation mode. This module is Android-only; iOS and web are no-ops.
+This module exposes a tiny JS/TS API and includes Android and iOS native source. The runtime behavior is Android-only; iOS/web are no-ops.
 
-## Install (local development with pnpm)
+---
 
-From the module repo:
+## Usage
 
-- `pnpm install`
-- (optional) `pnpm build` — runs the expo-module build scripts
+### Install
 
-From your Expo app project:
+- From your app project (local development):
+  - `pnpm add ../path/to/expo-rotation-module` (or use a published package: `pnpm add expo-rotation-module`)
 
-- Add the module locally: `pnpm add ../expo-rotation-module` (or `pnpm add file:../expo-rotation-module`)
-- IMPORTANT: Add the plugin to your app config so the permission is injected during prebuild:
+- IMPORTANT: add the config plugin to your app config so the permission is injected during `prebuild`.
 
-  In `app.json` or `app.config.js` add the following to your `expo.plugins` array:
+  In `app.json` or `app.config.js` add the package name to `expo.plugins`:
 
   ```json
-  "plugins": [
-    "expo-rotation-module"
-  ]
+  {
+    "expo": {
+      "plugins": [
+        "expo-rotation-module"
+      ]
+    }
+  }
   ```
 
-- Run `npx expo prebuild` to apply the config plugin and update `AndroidManifest.xml`.
-- Rebuild the Android app (use EAS dev client or Android Studio):
-  - Recommended: `pnpm add expo-dev-client` then `eas build --profile development --platform android` and run with `expo start --dev-client`.
+  - The plugin is implemented in `plugin/index.js` and will insert the `WRITE_SETTINGS` permission into your `AndroidManifest.xml` during `expo prebuild`.
+
+- Apply native changes and build the app:
+  - `npx expo prebuild` (or `expo run:android` which runs prebuild automatically)
+  - Rebuild/install the app on device/emulator (use a custom dev client or a standalone build for WRITE_SETTINGS tests — Expo Go is not suitable).
 
-## API
+### API
 
-Import functions:
+Import the module in JS/TS:
 
 ```ts
-import Rotation, { canWrite, requestWritePermission, getRotationState, setRotationState } from 'expo-rotation-module';
+import Rotation, {
+  canWrite,
+  requestWritePermission,
+  getRotationState,
+  setRotationState,
+  getPackageName,
+} from 'expo-rotation-module';
 ```
 
-- `canWrite(): Promise<boolean>` — true if WRITE_SETTINGS is granted (Android M+), otherwise true on older OS.
-- `requestWritePermission(): void` — opens Settings where the user can grant WRITE_SETTINGS.
-- `getRotationState(): Promise<'AUTOROTATE'|'PORTRAIT'|'LANDSCAPE'>` — reads current rotation state.
-- `setRotationState(state): Promise<void>` — sets rotation. Rejects with an Error object that may include a `.code` property.
+- `canWrite(): Promise<boolean>` — returns true if the app has `WRITE_SETTINGS` granted (Android M+). Returns `true` on older OS versions.
+- `requestWritePermission(): void` — opens the Android Settings screen where the user can grant the permission for your app.
+- `getRotationState(): Promise<'AUTOROTATE'|'PORTRAIT'|'LANDSCAPE'>` — reads the current global rotation state.
+- `setRotationState(state): Promise<void>` — sets the rotation state. Rejects with an Error that may contain a `code` property (e.g. `E_PERMISSION`).
+- `getPackageName(): Promise<string>` — returns the package name the native module is using (useful for diagnostics).
 
-Error codes on the Error object (if available): `E_PERMISSION`, `E_INVALID_STATE`, `E_SET_ROTATION`, `E_GET_ROTATION`, `E_NO_MODULE`.
+All functions are Android-only. On non-Android platforms the functions are no-ops or return safe defaults.
 
-## Example
+### Example
 
 ```ts
-import * as Rotation from 'expo-rotation-module';
+import Rotation from 'expo-rotation-module';
 
-async function example() {
-  if (!(await Rotation.canWrite())) {
+async function ensureAndSet() {
+  const hasPermission = await Rotation.canWrite();
+  if (!hasPermission) {
+    // Opens Settings where the user can grant WRITE_SETTINGS for your app
     Rotation.requestWritePermission();
     return;
   }
 
-  try {
-    await Rotation.setRotationState('PORTRAIT');
-  } catch (e: any) {
-    if (e.code === 'E_PERMISSION') {
-      console.warn('Permission missing');
-    }
-  }
+  await Rotation.setRotationState('PORTRAIT');
 }
 ```
 
-## Plugin
-The package contains `plugin/index.js` that injects `android.permission.WRITE_SETTINGS` into the host app's AndroidManifest during `expo prebuild`.
+### Troubleshooting
 
-## Package id and Android settings
-The Android package/namespace used within module sources is `ktsierra.expo.rotationmodule`.
+- WRITE_SETTINGS switch is greyed out in the Settings screen:
+  - Ensure your app has the `WRITE_SETTINGS` permission declared in the manifest. The config plugin adds this when you run `expo prebuild`.
+  - Do not test this inside Expo Go — the Settings screen will target the Expo Go package. Build a custom dev client or standalone build.
+  - Confirm the package name by calling `Rotation.getPackageName()` and check device logs for the `Opening WRITE_SETTINGS for package: <pkg>` message.
 
-## Contributing & tests
-If you want CI or tests added (TS checks, build smoke tests), I can add a GitHub Actions workflow that runs `pnpm install` and `pnpm build`.
+- ESLint/type errors in consuming projects:
+  - Ensure your app can resolve the package. For local linking with pnpm workspaces, `pnpm install` in the app and a restart of the editor/TS server is sometimes required.
 
 ---
+
+## Development
+
+This section explains how to develop, test and publish this module.
+
+### Repo layout (important files)
+
+- `src/` — TypeScript JS wrapper and types.
+- `android/` — Android native sources (Kotlin) and Gradle files.
+- `ios/` — iOS native sources (Swift) and podspec.
+- `plugin/` — config plugin that injects the `WRITE_SETTINGS` permission.
+- `app.plugin.js` — plugin entry point for Expo to discover the config plugin.
+- `index.js` — package entry that re-exports the JS wrapper.
+- `package.json` — package metadata, scripts and publish config.
+
+### Local development
+
+1. Install dependencies in the module repo:
+   - `pnpm install`
+
+2. Make changes to `src/` or native code.
+
+3. Build/prepare artifacts (some scripts expect `tsc`/expo-module-scripts):
+   - `pnpm run prepare` (runs `expo-module prepare`) or `pnpm run build` (if you prefer).
+
+4. Test in an app:
+   - Create or use an example app. From the app root:
+     - Add the local package: `pnpm add ../path/to/expo-rotation-module` (or `pnpm add file:...`)
+     - Ensure `app.json` includes the plugin (see Usage).
+     - Run `npx expo prebuild` and verify `android/app/src/main/AndroidManifest.xml` contains `<uses-permission android:name="android.permission.WRITE_SETTINGS" />`.
+     - Build and run the app on device/emulator (`expo run:android` or a dev client build).
+
+5. Faster iteration (optional):
+   - Instead of building the package, map Metro to the module `src` in the app `metro.config.js` during development:
+     ```js
+     // example: app/metro.config.js
+     const path = require('path');
+     module.exports = {
+       resolver: {
+         extraNodeModules: {
+           'expo-rotation-module': path.resolve(__dirname, '../path/to/expo-rotation-module/src'),
+         },
+       },
+       watchFolders: [path.resolve(__dirname, '..')],
+     };
+     ```
+   - This lets the app load the TypeScript source directly without rebuilding the package on every change.
+
+### Publishing
+
+We publish the source package (native sources included). Before publishing, ensure:
+
+- `package.json` fields are correct (`name`, `version`, `main`, `types`, `files`).
+- `devDependencies` contains `typescript` so `expo-module prepare` runs in CI.
+- The plugin and native sources are included in the published package (use the `files` array in `package.json` to control this).
+
+Manual publish (local):
+
+1. Prepare the package locally:
+   - `pnpm install`
+   - `pnpm run prepare`
+
+2. Create a tarball to test what will be published:
+   - `npm pack`
+   - Install the tarball into a test app: `pnpm add ../expo-rotation-module-<version>.tgz`
+   - Run `npx expo prebuild` in the test app to confirm the plugin and native sources are applied.
+
+3. Publish:
+   - If your environment has an npm automation token configured in CI, run `npm publish --access public` from the package root.
+   - If `prepublishOnly` scripts fail in your environment, you can publish with scripts ignored after preparing locally:
+     - `npm publish --access public --ignore-scripts`
+
+### Continuous Integration / GitHub Actions
+
+- Recommended CI flow:
+  - `pnpm install --frozen-lockfile`
+  - `pnpm run prepare` (ensure `typescript` is installed in `devDependencies` so `tsc` is available)
+  - Run tests/lint (optional)
+  - Bump version, push tags
+  - Authenticate to npm (use an automation token or GitHub OIDC if your npm org supports trusted publishers)
+  - `npm publish --access public` or `pnpm publish --access public`
+
+- Example workflow (summary):
+  - Checkout, setup Node + pnpm, `pnpm install`, run `pnpm run prepare`, bump version, publish.
+
+---
+
+If you find anything missing or unclear (examples, API signatures, or CI details) open an issue or submit a PR. Contributions welcome.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-rotation-module",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "description": "Screen Orientation Native Module",
   "main": "index.js",
   "types": "src/index.d.ts",
@@ -36,6 +36,7 @@
   },
   "devDependencies": {
     "@types/react": "~19.1.0",
+    "typescript": "~5.9.2",
     "expo": "^54.0.27",
     "expo-module-scripts": "^5.0.8",
     "react-native": "0.81.5"

package/android/.gradle/buildOutputCleanup/cache.properties

@@ -1,2 +0,0 @@
-#Tue Jan 06 14:23:37 EST 2026
-gradle.version=9.2.0

package/android/.gradle/config.properties

@@ -1,2 +0,0 @@
-#Tue Jan 06 13:19:56 EST 2026
-java.home=/Applications/Android Studio.app/Contents/jbr/Contents/Home

package/android/.idea/AndroidProjectSystem.xml

@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project version="4">
-  <component name="AndroidProjectSystem">
-    <option name="providerId" value="com.android.tools.idea.GradleProjectSystem" />
-  </component>
-</project>