etherisc · christoph2806 · May 30, 2025 · May 30, 2025 · May 30, 2025
diff --git a/.changeset/config.json b/.changeset/config.json
@@ -4,7 +4,7 @@
   "commit": false,
   "fixed": [],
   "linked": [],
-  "access": "restricted",
+  "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
   "ignore": []

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -83,7 +83,8 @@
     3000, // Storybook
     5173, // Vite dev server
     4173, // Vite preview
-    8080 // API server
+    8080, // API server
+    9323 // Playwright UI mode
   ],
 
   // Use 'postCreateCommand' to run commands after the container is created

diff --git a/.devcontainer/docker-compose.yml b/.devcontainer/docker-compose.yml
@@ -34,13 +34,8 @@ services:
       # Persist Playwright browsers
       - playwright-browsers:/home/node/.cache/ms-playwright
 
-    # Forward ports for development
-    ports:
-      - "3000:3000"   # Storybook
-      - "5173:5173"   # Vite dev server
-      - "4173:4173"   # Vite preview
-      - "8080:8080"   # API server
-      - "9323:9323"   # Playwright UI mode
+    # Note: Port forwarding is handled by VS Code via devcontainer.json forwardPorts
+    # This prevents port conflicts with other containers on the host machine
 
     # Keep container running
     command: sleep infinity

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -101,7 +101,10 @@ jobs:
               .private = false | 
               .publishConfig.registry = "https://npm.pkg.github.com" |
               .repository.type = "git" |
-              .repository.url = $repo_url' \
+              .repository.url = $repo_url |
+              .scripts = {} |
+              del(.devDependencies) |
+              del(.size-limit)' \
              package.json > package.json.tmp && mv package.json.tmp package.json
 
           echo "Updated package.json for publishing:"
@@ -118,6 +121,44 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Setup Node.js for npm registry
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Update package.json for npm registry
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          VERSION_NO_V=${VERSION#v}
+
+          cd packages/ui-kit
+
+          # Update package.json for npm registry publishing
+          jq --arg name "@etherisc/ui-kit" \
+             --arg version "${VERSION_NO_V}" \
+             --arg repo_url "git+https://github.com/${{ github.repository }}.git" \
+             '.name = $name | 
+              .version = $version | 
+              .private = false | 
+              del(.publishConfig) |
+              .repository.type = "git" |
+              .repository.url = $repo_url |
+              .scripts = {} |
+              del(.devDependencies) |
+              del(.size-limit)' \
+             package.json > package.json.tmp && mv package.json.tmp package.json
+
+          echo "Updated package.json for npm registry:"
+          cat package.json | jq '.name, .version, .private, .repository'
+
+      - name: Publish to npm registry
+        run: |
+          cd packages/ui-kit
+          npm publish --access=public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
       - name: Setup Pages
         uses: actions/configure-pages@v4
         with:
@@ -177,11 +218,18 @@ jobs:
           ### 📦 Installation
 
           \`\`\`bash
+          # From npm registry (recommended)
           npm install @etherisc/ui-kit@${VERSION#v}
+          # or
+          pnpm add @etherisc/ui-kit@${VERSION#v}
+
+          # From GitHub Packages (alternative)
+          npm install @etherisc/ui-kit@${VERSION#v} --registry=https://npm.pkg.github.com
           \`\`\`
 
           ### 🔗 Links
-          - **Package**: [GitHub Packages](https://github.com/${{ github.repository }}/packages)
+          - **npm Package**: [npmjs.com](https://www.npmjs.com/package/@etherisc/ui-kit)
+          - **GitHub Package**: [GitHub Packages](https://github.com/${{ github.repository }}/packages)
           - **Demo**: [Storybook](${PAGE_URL})
           - **Build**: \`${BUILD_HASH}\`
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -366,20 +366,31 @@ We use [Changesets](https://github.com/changesets/changesets) for version manage
    pnpm changeset
    ```
 
-2. **Follow the prompts to describe your changes**
+2. **Changesets bot creates release PR**
 
-3. **Commit the changeset file**
-   ```bash
-   git add .changeset/
-   git commit -m "chore: add changeset for feature"
-   ```
+3. **Review and merge release PR to main**
+
+4. **Automated release process**:
+   - Publishes to npm registry (public access)
+   - Publishes to GitHub Packages
+   - Creates GitHub release with release notes
+   - Deploys Storybook to GitHub Pages
+
+### Publishing Destinations
+
+The package is automatically published to multiple registries:
+
+- **npm Registry** (recommended for consumers): `npm install @etherisc/ui-kit`
+- **GitHub Packages** (alternative): `npm install @etherisc/ui-kit --registry=https://npm.pkg.github.com`
+
+### Manual Release (Maintainers Only)
 
-### Release Workflow
+For manual releases, use the GitHub Actions workflow:
 
-1. Changesets bot creates release PR
-2. Review and merge release PR
-3. Automated release to npm and GitHub
-4. Storybook deployment to GitHub Pages
+1. Go to Actions → Release workflow
+2. Click "Run workflow"
+3. Enter the version tag (e.g., `v0.3.0-beta`)
+4. The workflow will build, test, and publish automatically
 
 ## Issue Reporting
 

diff --git a/README.md b/README.md
@@ -8,6 +8,65 @@ React component library and showcase admin app built with modern tools:
 - 🏗️ Vite + TypeScript + pnpm
 - 📚 Storybook + Vitest + Playwright
 
+## Installation
+
+### For Consumers (Using the UI Kit)
+
+Install the UI kit package in your React project:
+
+```bash
+# From npm registry (recommended)
+npm install @etherisc/ui-kit
+# or
+pnpm add @etherisc/ui-kit
+# or
+yarn add @etherisc/ui-kit
+
+# From GitHub Packages (alternative)
+npm install @etherisc/ui-kit --registry=https://npm.pkg.github.com
+```
+
+#### Peer Dependencies
+
+Make sure you have the required peer dependencies installed:
+
+```bash
+npm install react@>=18.0.0 react-dom@>=18.0.0
+```
+
+#### Basic Usage
+
+```tsx
+import { Button, TextInput, AppShell } from "@etherisc/ui-kit";
+import "@etherisc/ui-kit/dist/style.css";
+
+function App() {
+  return (
+    <AppShell>
+      <div className="p-4">
+        <h1>My App</h1>
+        <TextInput label="Name" placeholder="Enter your name" />
+        <Button variant="primary">Submit</Button>
+      </div>
+    </AppShell>
+  );
+}
+```
+
+#### Available Components
+
+- **Form Components**: Button, TextInput, NumberInput, Select, Checkbox, RadioGroup, DatePicker
+- **Layout Components**: AppShell, AuthShell, MainLayout
+- **Data Components**: DataTable with pagination and sorting
+- **Feedback Components**: Toast system, StatusBadge, ErrorBoundary
+- **Editor Components**: MarkdownEditor, CodeEditor
+
+For complete documentation and examples, visit our [Storybook](https://etherisc.github.io/ui-kit/).
+
+## Development Setup
+
+### For Contributors (Developing the UI Kit)
+
 ## Quick Start
 
 ### Option 1: DevContainer (Recommended)

diff --git a/docs/task-planning/fix-package-installation-issue-36.md b/docs/task-planning/fix-package-installation-issue-36.md
@@ -0,0 +1,88 @@
+# Task Planning: Fix Package Installation Issue #36
+
+**GitHub Issue**: #36 - Package installation fails when used as dependency - blocks all consumers  
+**Priority**: HIGH - Critical blocker for all package consumers  
+**Estimated Duration**: 1-2 days  
+**Branch**: `fix/package-installation-issue-36`
+
+## Problem Summary
+
+The `@etherisc/ui-kit` package cannot be installed as a dependency in consumer projects due to:
+
+1. Husky prepare script failing in consumer environments
+2. Package marked as private preventing npm publishing
+3. Monorepo structure confusion for consumers
+4. Missing proper peer dependencies configuration
+
+## Task Breakdown
+
+| Task Description                                                                                                                  | DoD (Definition of Done)                                                                                                                           | Status   |
+| --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| **1. Fix Husky Prepare Script** - Update root package.json prepare script to be conditional and not fail in consumer environments | Root package.json prepare script runs without error when package is installed as dependency; test installation in sample consumer project succeeds | Complete |
+| **2. Make UI Kit Package Publishable** - Remove private flag and configure package.json for npm publishing                        | packages/ui-kit/package.json has private: false; proper peer dependencies defined; package can be published to npm                                 | Complete |
+| **3. Configure npm Publishing** - Update changesets config and GitHub Actions for npm registry publishing                         | .changeset/config.json updated for public access; GitHub Actions workflow can publish to npm registry; npm publish workflow exists                 | Complete |
+| **4. Optimize Package for Consumers** - Clean up package.json scripts and dependencies for consumer use                           | Only essential scripts remain in published package.json; dev dependencies properly separated; bundle size optimized                                | Complete |
+| **5. Test Package Installation** - Create test consumer project and verify installation works                                     | Can install via `pnpm add @etherisc/ui-kit`; can install via `pnpm add github:etherisc/ui-kit`; components import and render correctly             | Complete |
+| **6. Update Documentation** - Add installation instructions and usage examples                                                    | README.md includes clear installation instructions; CONTRIBUTING.md updated with publishing workflow                                               | Complete |
+
+## Technical Implementation Details
+
+### Phase 1: Immediate Fixes
+
+- Update root `package.json` prepare script to be conditional
+- Remove `"private": true` from ui-kit package.json
+- Add proper peer dependencies (React 18+)
+- Configure proper package exports
+
+### Phase 2: Publishing Setup
+
+- Update changesets configuration for public access
+- Configure GitHub Actions for npm publishing
+- Test publishing workflow
+
+### Phase 3: Consumer Optimization
+
+- Remove development-only scripts from published package
+- Ensure proper file inclusion via "files" field
+- Optimize bundle for consumer use
+
+### Phase 4: Testing & Documentation
+
+- Create sample consumer project for testing
+- Test both npm and GitHub installation methods
+- Update documentation with installation instructions
+
+## Expected Outcomes
+
+After completion:
+
+- ✅ Consumers can install package without errors
+- ✅ Package available on npm registry with proper versioning
+- ✅ GitHub installation method also works reliably
+- ✅ Reduced installation overhead (no dev dependencies)
+- ✅ Clear documentation for consumers
+
+## Test Criteria
+
+1. **Installation Test**: `pnpm add @etherisc/ui-kit` completes successfully
+2. **GitHub Installation Test**: `pnpm add github:etherisc/ui-kit` completes successfully
+3. **Import Test**: Components can be imported: `import { Button } from '@etherisc/ui-kit'`
+4. **Build Test**: Consumer project builds successfully with ui-kit components
+5. **Runtime Test**: Components render and function correctly in consumer app
+
+## Dependencies
+
+- Requires access to npm registry for publishing
+- May need GitHub token with package write permissions
+- Changesets configuration for version management
+
+## Risks & Mitigation
+
+**Risk**: Breaking existing development workflow  
+**Mitigation**: Test all development commands after changes
+
+**Risk**: Publishing misconfiguration  
+**Mitigation**: Test publishing in separate environment first
+
+**Risk**: Bundle size increase for consumers  
+**Mitigation**: Verify file inclusion and exclude dev dependencies
diff --git a/package.json b/package.json
@@ -14,7 +14,7 @@
     "test:a11y:specific": "cd packages/ui-kit && pnpm run test-storybook:specific",
     "lint": "pnpm -r lint",
     "format": "prettier --write \"**/*.{ts,tsx,md}\"",
-    "prepare": "husky install"
+    "prepare": "node -e \"try { require('fs').existsSync('.git') && require('husky').install() } catch (e) {}\""
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.4",

diff --git a/packages/ui-kit/package.json b/packages/ui-kit/package.json
@@ -1,7 +1,6 @@
 {
   "name": "@etherisc/ui-kit",
   "version": "0.2.0-beta",
-  "private": true,
   "type": "module",
   "license": "Apache-2.0",
   "main": "./dist/ui-kit.umd.cjs",
@@ -18,6 +17,10 @@
   "files": [
     "dist/**"
   ],
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
@@ -65,8 +68,6 @@
     "@radix-ui/react-slot": "^1.2.3",
     "@sentry/browser": "^9.22.0",
     "@sentry/react": "^9.22.0",
-    "@testing-library/user-event": "^14.6.1",
-    "@types/testing-library__jest-dom": "^6.0.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
@@ -75,12 +76,9 @@
     "dompurify": "^3.2.6",
     "i18next": "^25.2.1",
     "i18next-browser-languagedetector": "^8.1.0",
-    "jsdom": "^26.1.0",
     "lucide-react": "^0.511.0",
     "marked": "^15.0.12",
-    "react": "^19.1.0",
     "react-day-picker": "8.10.1",
-    "react-dom": "^19.1.0",
     "react-hook-form": "^7.56.4",
     "react-i18next": "^15.5.2",
     "tailwind-merge": "^2.6.0",
@@ -126,11 +124,13 @@
     "@testing-library/dom": "^10.0.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
     "@types/dompurify": "^3.2.0",
     "@types/jest": "^29.5.14",
     "@types/marked": "^6.0.0",
     "@types/react": "^19.1.4",
     "@types/react-dom": "^19.1.5",
+    "@types/testing-library__jest-dom": "^6.0.0",
     "@types/testing-library__react": "^10.2.0",
     "@vitejs/plugin-react": "^4.4.1",
     "@vitest/coverage-v8": "^1.6.1",
@@ -143,6 +143,7 @@
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-react-refresh": "^0.4.20",
+    "jsdom": "^26.1.0",
     "postcss": "^8.5.3",
     "prop-types": "^15.8.1",
     "react": "^19.1.0",