@tap-payments/os-micro-frontend-shared 0.1.491 → 0.1.492-test.2

package/docs/02-setup.md

@@ -0,0 +1,326 @@
+# Setup Guide
+
+Complete setup instructions for installing, developing, and deploying the component library.
+
+## Table of Contents
+
+1. [Prerequisites](#prerequisites) - System requirements and tools
+2. [Installation](#installation) - Getting started
+3. [Development](#development) - Local development workflow
+4. [Building](#building) - Compilation process
+5. [Testing Locally](#testing-locally) - Testing in consumer apps
+6. [Publishing](#publishing) - Staging and production releases
+7. [CI/CD](#cicd) - Automated pipelines
+8. [Troubleshooting](#troubleshooting) - Common issues and solutions
+
+## Prerequisites
+
+| Requirement | Version | Purpose |
+|-------------|---------|---------|
+| Node.js | 18.x+ | Runtime environment |
+| npm or yarn | Latest | Package manager |
+| Git | Latest | Version control |
+| yalc (optional) | Latest | Local package testing |
+
+**Verify installation:**
+
+```bash
+node --version    # v18.0.0+
+npm --version     # 9.0.0+
+yarn --version    # 1.22.0+
+```
+
+## Installation
+
+### Clone and Install
+
+```bash
+# Clone repository
+git clone <repository-url>
+cd os-micro-frontend-shared
+
+# Install dependencies
+yarn install
+# or
+npm install
+```
+
+### Post-Install
+
+Husky hooks are automatically installed via the `prepare` script:
+- Pre-commit: runs `lint-staged` (prettier + lint)
+
+## Development
+
+### Start Dev Server
+
+```bash
+yarn dev
+# or
+npm run dev
+```
+
+- **URL**: http://localhost:3010
+- **Hot Module Replacement**: Enabled
+- **Demo components**: Available in `src/demo/`
+
+### Quick Command Reference
+
+| Task | Command | When to Use |
+|------|---------|-------------|
+| Install | `yarn install` | First time setup, after pulling changes |
+| Dev server | `yarn dev` | Testing components locally at localhost:3010 |
+| Build library | `yarn ts:build` | Before publishing or testing in consumers |
+| Lint | `yarn lint` | Check for code errors |
+| Fix lint | `yarn lint:fix` | Auto-fix linting issues |
+| Format | `yarn prettier:fix` | Auto-format code |
+| Local test | `yarn push:local` | Test changes in consuming apps (requires yalc) |
+| Test publish | `yarn push:test` | Publish test version to npm with -test tag |
+| Prod publish | `yarn push` | Manual production publish (usually auto via CI) |
+| Clean | `rm -rf node_modules build && yarn install` | Fix dependency/build issues |
+
+## Building
+
+### Build for npm Publishing
+
+```bash
+yarn ts:build
+```
+
+**Build process:**
+1. `rm -rf build` - Clean previous build
+2. `tsc -p tsconfig.npm.json` - Compile TypeScript to JavaScript
+3. Generate `.d.ts` type definition files
+4. `tsc-alias` - Resolve path aliases (@components → ./components)
+
+**Output:**
+
+```
+build/
+├── index.js, index.d.ts
+├── components/
+├── hooks/
+├── utils/
+├── types/
+├── constants/
+└── theme/
+```
+
+### Build Configuration
+
+| Setting | Value | Purpose |
+|---------|-------|---------|
+| Format | ESM only | Modern modules for tree-shaking |
+| Target | ES2015 | Browser compatibility |
+| Modules | Preserved | Maintains folder structure |
+| Declarations | true | Generates .d.ts files |
+
+## Testing Locally
+
+### Option 1: Using yalc (Recommended)
+
+```bash
+# In this library
+yarn push:local
+
+# In consumer app
+yalc add @tap-payments/os-micro-frontend-shared
+yarn install
+```
+
+### Option 2: Using npm link
+
+```bash
+# In this library
+yarn ts:build
+npm link
+
+# In consumer app
+npm link @tap-payments/os-micro-frontend-shared
+```
+
+### Option 3: Test Version on npm
+
+```bash
+# In this library
+yarn push:test
+
+# In consumer app
+npm install @tap-payments/os-micro-frontend-shared@test
+```
+
+## Publishing
+
+### Test/Staging Publish
+
+```bash
+yarn push:test
+```
+
+**What happens:**
+1. Version becomes `0.1.404-test.N` (increments test counter)
+2. Builds library with `yarn ts:build`
+3. Publishes to npm with `--tag test`
+4. Restores original version in package.json
+
+**Install in consumer:**
+
+```bash
+npm install @tap-payments/os-micro-frontend-shared@test
+```
+
+### Production Publish
+
+**Automatic (Recommended):**
+1. Create PR to main branch
+2. After merge → GitHub Action runs:
+   - Bumps patch version
+   - Commits version change
+   - Builds library
+   - Publishes to npm
+
+**Manual (if needed):**
+
+```bash
+yarn push
+```
+
+## CI/CD
+
+### GitHub Actions Workflows
+
+| Workflow | Trigger | Actions |
+|----------|---------|---------|
+| code-checks.yml | Push to any branch | lint, prettier, build verification |
+| publish.yml | PR merge to main | Version bump, build, npm publish |
+
+### Code Checks Workflow
+
+**Runs on:** Every push (if `src/**` files changed)
+
+**Steps:**
+1. Checkout code
+2. Setup Node.js 18.x
+3. Install dependencies
+4. Run lint check
+5. Run prettier check
+6. Run build verification
+
+### Auto-Publish Workflow
+
+**Runs on:** PR merge to main
+
+**Steps:**
+1. Checkout main branch
+2. Setup Node.js 22.x
+3. Install dependencies
+4. Bump patch version
+5. Commit version change
+6. Build library (`yarn ts:build`)
+7. Publish to npm (public)
+
+## Troubleshooting
+
+### Common Issues
+
+| Problem | Solution |
+|---------|----------|
+| Component not found | Check `src/components/index.ts` for export |
+| Build fails | `rm -rf build && yarn ts:build` |
+| Lint errors | `yarn lint:fix` |
+| Format issues | `yarn prettier:fix` |
+| yalc not updating | `yarn push:local` in library, `yalc update` in consumer |
+| Types not found | Check `build/` has `.d.ts` files after `yarn ts:build` |
+| Vite cache issues | `rm -rf node_modules/.vite` in consumer |
+| Pre-commit fails | `yarn prettier:fix && yarn lint:fix` |
+
+### Debug Commands
+
+```bash
+# Check what will be published
+npm pack --dry-run
+
+# View package exports
+cat package.json | grep -A 50 '"exports"'
+
+# Verify build output structure
+ls -la build/
+ls -la build/components/
+
+# Check published versions
+npm view @tap-payments/os-micro-frontend-shared versions
+
+# Check test tag versions
+npm view @tap-payments/os-micro-frontend-shared dist-tags
+```
+
+### Clean Rebuild
+
+```bash
+# Full clean rebuild
+rm -rf node_modules build
+yarn install
+yarn ts:build
+```
+
+## Git Workflow
+
+### Standard PR Flow
+
+```bash
+# 1. Create feature branch
+git checkout -b feature/my-feature
+
+# 2. Make changes in src/
+
+# 3. Commit (triggers pre-commit hooks)
+git add .
+git commit -m "feat: description"
+
+# 4. Push to GitHub
+git push origin feature/my-feature
+
+# 5. Create PR to main
+
+# 6. After merge → auto-publishes to npm
+```
+
+### Pre-commit Hooks
+
+**What runs:**
+1. `prettier:fix` - Auto-formats staged files
+2. `lint` - Checks for errors
+
+**Files checked:** `src/**/*.{ts,tsx,json,js,jsx}`
+
+## Environment Variables
+
+### Development
+
+No environment variables required for local development.
+
+### CI/CD (GitHub Actions)
+
+| Variable | Purpose | Required For |
+|----------|---------|--------------|
+| NPM_TOKEN | npm authentication | Publishing |
+| GH_TOKEN | GitHub API access | Version commits |
+
+## Configuration Files
+
+| File | Purpose |
+|------|---------|
+| package.json | Dependencies, scripts, exports |
+| tsconfig.json | Base TypeScript config |
+| tsconfig.npm.json | Build config for npm |
+| vite.config.ts | Vite dev server & build |
+| eslint.config.js | ESLint rules |
+| .prettierrc | Prettier formatting |
+| .husky/pre-commit | Git pre-commit hook |
+
+## Next Steps
+
+- [Overview](./01-overview.md) - Project purpose and features
+- [Architecture](./03-architecture.md) - System design details
+- [Component Guide](./04-component-guide.md) - Component catalog and selection
+- [Building Components](./05-component-development.md) - Creating new components