@wireservers-ui/react-natives 1.0.1-rc2 → 1.0.1

package/README.md

@@ -34,40 +34,122 @@ React-Natives is a collection of 70+ production-ready, accessible React Native c
 
 ---
 
-## Quick Start
+## Quick Start (Easy Setup)
 
-### Install
+### Option A: Fully Automated Setup (Recommended)
+
+Use this when starting a new Expo consumer app for the first time.
 
 ```bash
-npm install @wireservers-ui/react-natives
+npx create-expo-app@latest wsui-init --template blank-typescript
+cd wsui-init
+npm install @wireservers-ui/react-natives@1.0.1
+npx @wireservers-ui/react-natives@1.0.1 init
+npx expo start --clear --web
 ```
 
-### Peer Dependencies
+The `init` command will:
+
+- Install required runtime styling packages
+- Match `react-dom` to your installed `react` version exactly (prevents React/DOM mismatch)
+- Create config files only when missing
+- Never overwrite existing app/config files in your project
+- Generate a working volume-slider demo in `App.tsx` only if `App.tsx` does not already exist
+
+### Option B: Manual Setup
+
+If you prefer full manual control:
 
 ```bash
-npm install nativewind tailwind-variants react-native-reanimated react-native-gesture-handler react-native-svg
+npm install @wireservers-ui/react-natives
+npm install nativewind tailwindcss tailwind-variants tailwind-merge react-native-reanimated react-native-worklets react-native-svg react-native-web react-dom
 ```
 
-`react-native-reanimated`, `react-native-gesture-handler`, and `react-native-svg` are optional — only required by components that use them.
+Then configure Tailwind, Babel, Metro, and theme CSS yourself.
 
-### Configure Tailwind
+---
 
-Add the preset to your `tailwind.config.js`:
+## Setup Changes (What, How, Why)
 
-```js
-/** @type {import('tailwindcss').Config} */
-module.exports = {
-  content: [
-    "./app/**/*.{js,jsx,ts,tsx}",
-    // ...your content paths
-  ],
-  presets: [require("@wireservers-ui/react-natives/tailwind-preset")],
-};
-```
+This section documents the major setup hardening changes made to ensure reliable first-time consumer setup.
+
+### 1. Added CLI init bootstrap command
+
+- What changed:
+  Added `bin/cli.js` and package `bin` mapping so consumers can run `npx @wireservers-ui/react-natives init`.
+- How:
+  The CLI writes Tailwind, Babel, Metro, and theme files and installs missing runtime dependencies.
+- Why:
+  Consumer setup was too error-prone and required manual multi-file configuration.
+
+### 2. Fixed Babel NativeWind wiring
+
+- What changed:
+  `nativewind/babel` is now configured in `presets` (not `plugins`).
+- How:
+  The generated `babel.config.js` uses:
+  `presets: [["babel-preset-expo", { jsxImportSource: "nativewind" }], "nativewind/babel"]`.
+- Why:
+  Wrong placement caused Babel runtime errors and failed bundling.
+
+### 3. Added missing runtime dependencies for modern Expo stack
 
-The preset includes the NativeWind preset, the full color/theme system, content scanning of the library, and safelist rules — no additional configuration needed.
+- What changed:
+  Init installs `react-native-worklets`, `react-native-svg`, `tailwind-merge`, and web deps.
+- How:
+  Dependency install list in the CLI now includes all required packages for both native and web usage.
+- Why:
+  Missing deps caused runtime/bundling failures (`react-native-worklets/plugin`, SVG resolution, variant merge errors).
+
+### 4. React + React DOM version lockstep
+
+- What changed:
+  Init now reads the installed `react` version from consumer `node_modules` and installs `react-dom@<exact-react-version>`.
+- How:
+  CLI helper resolves `node_modules/react/package.json` and builds a matching `react-dom` install target.
+- Why:
+  React web requires exact version parity; mismatch causes immediate runtime failure.
+
+### 5. Tailwind content scanning extended for package source
+
+- What changed:
+  Generated `tailwind.config.js` now includes:
+  `./node_modules/@wireservers-ui/react-natives/src/**/*.{js,jsx,ts,tsx}`
+- How:
+  The content path is emitted by init when creating Tailwind config.
+- Why:
+  Without this, many library utility classes are not generated in consumer CSS, causing missing colors and broken visual behavior.
+
+### 6. pnpm compatibility for Metro
+
+- What changed:
+  Init creates/updates `.npmrc` with `node-linker=hoisted` when pnpm is detected, then reinstalls before package additions.
+- How:
+  CLI detects lockfile, applies hoisted linker, and runs a reinstall pass.
+- Why:
+  Default pnpm linking can break Metro module resolution in Expo projects.
+
+### 7. Non-destructive init behavior
+
+- What changed:
+  Init no longer overwrites existing project files.
+- How:
+  All file writes now follow create-if-missing semantics and print a skip message for existing files.
+- Why:
+  Consumers must keep control of their app and config files; setup tooling should be safe by default.
+
+### 8. Published iterative release candidates
+
+- What changed:
+  Setup fixes were shipped progressively and are now available in stable `1.0.1`.
+- How:
+  Verified through clean consumer project runs (`create-expo-app -> install -> init -> expo start`).
+- Why:
+  Each release isolated and validated one class of setup problems, reducing regression risk.
+
+---
 
-### Use Components
+## Example Usage
 
 ```tsx
 import { Button, ButtonText, Card, CardHeader, CardBody } from "@wireservers-ui/react-natives";

package/bin/cli.js

@@ -344,7 +344,7 @@ writeFile("App.tsx", appTsx);
 
 // ── Done ───────────────────────────────────────────────────────────────────
 console.log("\n✅ Setup complete!\n");
-console.log("   Created/updated:");
+console.log("   Created if missing (existing files were preserved):");
 console.log("     • tailwind.config.js");
 console.log("     • global.css (with theme variables)");
 console.log("     • nativewind-env.d.ts");
@@ -357,10 +357,12 @@ console.log("     npx expo start --clear\n");
 // ── Helpers ────────────────────────────────────────────────────────────────
 function writeFile(name, content) {
   const filePath = path.join(cwd, name);
+  if (fs.existsSync(filePath)) {
+    console.log(`   ⏭️  ${name} already exists, skipping`);
+    return;
+  }
   fs.writeFileSync(filePath, content, "utf8");
-  console.log(
-    `   ✏️  ${fs.existsSync(filePath) ? "Updated" : "Created"} ${name}`,
-  );
+  console.log(`   ✏️  Created ${name}`);
 }
 
 function writeIfMissing(name, content) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireservers-ui/react-natives",
-  "version": "1.0.1-rc2",
+  "version": "1.0.1",
   "description": "A comprehensive React Native component library built with NativeWind and Tailwind Variants",
   "main": "src/index.ts",
   "types": "src/index.ts",