@moneymap/ui 0.0.3-alpha.0 → 0.0.3

package/README.md

@@ -1,7 +1,283 @@
 # @moneymap/ui
 
-This library was generated with [Nx](https://nx.dev).
+This guide explains how to build and publish the `@moneymap/ui` library to npm registry.
 
-## Running unit tests
+## Prerequisites
 
-Run `nx test @moneymap/ui` to execute the unit tests via [Jest](https://jestjs.io).
+- Node.js and pnpm installed
+- npm account with access to publish to `@moneymap` scope
+- Access to the MoneyMap monorepo
+
+## Project Structure
+
+```
+libs/ui/
+├── src/                   # Source components
+├── dist/                  # Build output (generated)
+├── package.json           # Package configuration
+├── rollup.config.cjs      # Build configuration
+└── README.md              # This file
+```
+
+## Publishing Workflow
+
+### 1. Clean and Build
+
+Reset Nx cache and build the library:
+
+```bash
+# From workspace root
+nx reset
+nx build ui
+```
+
+This generates the build output in `libs/ui/dist/`:
+- `dist/index.esm.js` - Compiled JavaScript bundle
+- `dist/index.d.ts` - TypeScript declarations
+- `dist/src/` - Source files for `@moneymap/source` export
+
+### 2. Login to npm
+
+Ensure you're logged into npm with an account that has publish access:
+
+```bash
+npm login
+```
+
+Verify your login:
+
+```bash
+npm whoami
+```
+
+### 3. Test Package (Dry Run)
+
+Preview what will be published without actually publishing:
+
+```bash
+cd libs/ui
+npm pack --dry-run
+```
+
+**Expected output should include:**
+- ✅ `dist/index.esm.js`
+- ✅ `dist/index.d.ts`
+- ✅ `dist/src/` (source files)
+- ✅ `package.json`
+- ✅ `README.md`
+- ❌ No config files (`.babelrc`, `rollup.config.cjs`, `tsconfig.*`)
+
+### 4. Version Bump
+
+**Important:** You must increment the version before publishing.
+
+#### For Prerelease (Alpha/Beta)
+
+```bash
+# From libs/ui/
+npm version prerelease --preid=alpha
+# Example: 0.0.1-alpha.0 → 0.0.1-alpha.1
+# Example: 0.0.1-beta.0 → 0.0.1-beta.1
+```
+
+#### For Patch Release
+
+```bash
+npm version patch
+# Example: 0.0.1 → 0.0.2
+```
+
+#### For Minor Release
+
+```bash
+npm version minor
+# Example: 0.0.1 → 0.1.0
+```
+
+#### For Major Release
+
+```bash
+npm version major
+# Example: 0.0.3 → 1.0.0
+```
+
+#### Manual Version Update
+
+Alternatively, edit `libs/ui/package.json` directly:
+
+```json
+{
+  "version": "0.0.1"
+}
+```
+
+### 5. Publish to npm
+
+#### Publish Prerelease (Alpha/Beta)
+
+```bash
+# From libs/ui/
+npm publish --tag alpha --access public
+```
+
+This publishes with the `alpha` tag, so it won't become the default `latest` version.
+
+**Installing prerelease:**
+```bash
+npm install @moneymap/ui@alpha
+# or specific version
+npm install @moneymap/ui@0.0.3-alpha.1
+```
+
+#### Publish Stable Release
+
+```bash
+# From libs/ui/
+npm publish --access public
+```
+
+This publishes with the `latest` tag (default).
+
+**Installing stable:**
+```bash
+npm install @moneymap/ui
+```
+
+### 6. Verify Publication
+
+Check the published package:
+
+```bash
+npm view @moneymap/ui
+
+# Check all versions
+npm view @moneymap/ui versions
+
+# Check dist-tags
+npm view @moneymap/ui dist-tags
+```
+
+## Quick Reference Commands
+
+```bash
+# Full deployment workflow (stable release)
+nx reset
+nx build ui
+cd libs/ui
+npm pack --dry-run              # Verify package contents
+npm version patch               # Bump version
+npm publish --access public     # Publish
+
+# Full deployment workflow (prerelease)
+nx reset
+nx build ui
+cd libs/ui
+npm pack --dry-run
+npm version prerelease --preid=alpha
+npm publish --tag alpha --access public
+```
+
+## Troubleshooting
+
+### Cannot publish over previously published version
+
+You're trying to publish a version that already exists. Bump the version number:
+
+```bash
+npm version patch
+```
+
+### Package includes unwanted files
+
+Check the `files` field in `libs/ui/package.json`:
+
+```json
+{
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts"
+  ]
+}
+```
+
+Run `npm pack --dry-run` to preview before publishing.
+
+## Package Configuration
+
+### package.json
+
+The `libs/ui/package.json` controls what gets published:
+
+```json
+{
+  "name": "@moneymap/ui",
+  "version": "0.0.1",
+  "main": "./dist/index.esm.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "@moneymap/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts"
+  ]
+}
+```
+
+### rollup.config.cjs
+
+The build configuration uses Rollup with SWC for fast compilation:
+
+```javascript
+module.exports = withNx({
+  main: './src/index.ts',
+  outputPath: './dist',
+  compiler: 'swc',
+  format: ['esm'],
+  external: ['react', 'react-dom', 'react/jsx-runtime'],
+  assets: [
+    { input: '.', output: '.', glob: 'README.md' },
+    {
+      input: './src',
+      output: './src',
+      glob: '**/*.ts',
+      ignore: ['**/*.spec.ts', '**/*.test.ts'],
+    },
+    {
+      input: './src',
+      output: './src',
+      glob: '**/*.tsx',
+      ignore: ['**/*.spec.tsx', '**/*.test.tsx'],
+    },
+  ]
+});
+```
+
+## Version Strategy
+
+- **Prerelease (alpha/beta):** For testing new features
+  - Format: `0.0.1-alpha.0`, `0.0.1-beta.1`
+  - Publish with: `npm publish --tag alpha`
+
+- **Patch (0.0.x):** Bug fixes and minor changes
+  - Command: `npm version patch`
+
+- **Minor (0.x.0):** New features, backward compatible
+  - Command: `npm version minor`
+
+- **Major (x.0.0):** Breaking changes
+  - Command: `npm version major`
+
+## Support
+
+For questions or issues, contact the MoneyMap development team.