@mohasinac/appkit 2.1.3 → 2.3.0

package/README.md

@@ -1,51 +1,101 @@
 # @mohasinac/appkit
 
-Standalone core library repository for shared contracts, providers, UI primitives, and feature modules used by consumer apps such as `letitrip.in`.
+Appkit is a TypeScript package that provides shared contracts, feature modules, UI helpers, repositories, and runtime-aware utilities for Next.js and React applications.
 
-## Standalone Model
+## Package Info
 
-- `appkit` is published to npm as `@mohasinac/appkit`.
-- Consumer apps install from npm registry in production/CI/server flows.
-- Local watch/prerelease testing can be done manually without coupling repositories.
+- Name: `@mohasinac/appkit`
+- Current version: `2.3.0`
+- Module type: ESM
+- Main export: `dist/index.js`
 
-## Install (Consumer Apps)
+## Installation
 
 ```bash
 npm install @mohasinac/appkit
 ```
 
-## Common Subpath Imports
-
-- `@mohasinac/appkit/contracts`
-- `@mohasinac/appkit/core`
-- `@mohasinac/appkit/http`
-- `@mohasinac/appkit/errors`
-- `@mohasinac/appkit/utils`
-- `@mohasinac/appkit/validation`
-- `@mohasinac/appkit/ui`
-- `@mohasinac/appkit/next`
-- `@mohasinac/appkit/react`
-- `@mohasinac/appkit/providers/*`
-- `@mohasinac/appkit/features/*`
-
-## Development
+Install peer dependencies required by the features you use:
 
 ```bash
-npm install
-npm run watch
+npm install react react-dom next next-intl @tanstack/react-query
 ```
 
-## Build and Quality
+Optional peer dependencies (only if your integration uses them):
+
+- `firebase-admin`
+- `resend`
+- `razorpay`
+
+## Build Appkit Locally
 
 ```bash
 npm run build
-npm run lint
-npm run typecheck
-npm run index:generate
 ```
 
+This compiles the package to `dist/` using `tsconfig.build.json`.
+
+## Basic Consumer Usage
+
+```ts
+import {
+  // contracts
+  type ApiResponse,
+  // constants
+  API_ENDPOINTS,
+  // utilities
+  createApiEndpointResolver,
+} from "@mohasinac/appkit";
+```
+
+Appkit currently exposes a single barrel entrypoint. Import from the package root unless a migration guideline in your app says otherwise.
+
+## Runtime Handling for Consumers
+
+Because Appkit includes both server-capable and browser-only modules, consumers must choose where code runs.
+
+1. Use shared utilities, types, schemas, and config constants anywhere.
+2. Use server-only code only in server contexts (server actions, route handlers, backend code).
+3. Render browser-only modules from client components.
+4. If a browser-only component must be loaded from an SSR route, use dynamic import with SSR disabled.
+
+Example for browser-only modules in an SSR page:
+
+```tsx
+import dynamic from "next/dynamic";
+
+const ClientWidget = dynamic(
+  () => import("@mohasinac/appkit").then((m) => m.ClientWidget),
+  { ssr: false },
+);
+```
+
+## Consumer Responsibilities
+
+When integrating Appkit, keep these boundaries in your application:
+
+1. Keep secrets in server-only environment files and never expose them in client bundles.
+2. Initialize SDKs once in provider/config bootstrap code.
+3. Keep page-level data fetching in your app's page or server layer; pass data to Appkit views/components.
+4. Wrap writes/mutations in server actions or backend handlers.
+5. Use Appkit repositories/contracts rather than bypassing with ad hoc direct SDK calls.
+
+## Adding New Components or Code to Appkit
+
+Use this checklist when contributing:
+
+1. Place code in the appropriate domain folder under `src/` (`features/`, `core/`, `contracts/`, `utils/`, etc.).
+2. Export new symbols from the local domain barrel (`index.ts`) and then from `src/index.ts` if public.
+3. Keep runtime boundaries explicit:
+   - Browser API usage (`window`, `document`, `navigator`, `localStorage`) belongs to client-only modules.
+   - Node/server SDK usage belongs to server-only modules.
+   - Pure helpers stay framework-agnostic.
+4. Prefer type-safe contracts and schema validation for new APIs and forms.
+5. Run `npm run build` and fix all TypeScript errors before publishing.
+6. Add or update docs when new exports change consumer behavior.
+
 ## Publishing Notes
 
-- Publish new versions from this repository only.
-- Keep exported API and subpath entries aligned with `package.json` exports.
-- Consumer repositories should depend on registry versions, not committed file/link specs.
+- Only `dist/` is published (`files` field in `package.json`).
+- Ensure build output is up to date before release.
+- Validate exported API surface from `src/index.ts` before version bump.