Create framework library templates

.github/workflows/publish-packages.yml

@@ -0,0 +1,154 @@
+name: Publish Framework Packages
+
+on:
+  workflow_dispatch:
+    inputs:
+      package:
+        description: 'Package to publish (react, nextjs, nextjs-server, vue, svelte, or all)'
+        required: true
+        type: choice
+        options:
+          - all
+          - react
+          - nextjs
+          - nextjs-server
+          - vue
+          - svelte
+      version:
+        description: 'Version bump type'
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+      dry-run:
+        description: 'Dry run (do not publish)'
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        package: ${{ github.event.inputs.package == 'all' && fromJSON('["react", "nextjs", "nextjs-server", "vue", "svelte"]') || fromJSON(format('["{0}"]', github.event.inputs.package)) }}
+
+    permissions:
+      contents: write
+      packages: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }}
+
+      - uses: pnpm/action-setup@v4
+        name: Install pnpm
+        with:
+          version: 10
+          run_install: false
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install root dependencies
+        run: pnpm install --frozen-lockfile || pnpm install
+
+      - name: Install package dependencies
+        working-directory: ./${{ matrix.package }}
+        run: pnpm install || npm install
+
+      - name: Verify package files
+        working-directory: ./${{ matrix.package }}
+        run: |
+          echo "📦 Package contents:"
+          ls -la
+
+          echo ""
+          echo "📄 Files to be published:"
+          npm pack --dry-run 2>&1 | grep -A 100 "package:"
+
+      - name: Bump version
+        working-directory: ./${{ matrix.package }}
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+          # Get current version
+          CURRENT_VERSION=$(node -p "require('./package.json').version")
+          echo "Current version: $CURRENT_VERSION"
+
+          # Bump version
+          npm version ${{ github.event.inputs.version }} --no-git-tag-version
+
+          # Get new version
+          NEW_VERSION=$(node -p "require('./package.json').version")
+          echo "New version: $NEW_VERSION"
+          echo "NEW_VERSION=$NEW_VERSION" >> $GITHUB_ENV
+
+      - name: Verify version update
+        working-directory: ./${{ matrix.package }}
+        run: |
+          echo "✅ Version updated to: ${{ env.NEW_VERSION }}"
+          cat package.json | grep version
+
+      - name: Publish to npm (Dry Run)
+        if: github.event.inputs.dry-run == 'true'
+        working-directory: ./${{ matrix.package }}
+        run: |
+          echo "🔍 Dry run mode - would publish:"
+          npm pack --dry-run
+          ls -la
+
+      - name: Publish to npm
+        if: github.event.inputs.dry-run != 'true'
+        working-directory: ./${{ matrix.package }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          # Publish from root directory (includes source files)
+          npm publish --access public
+
+      - name: Commit version bump
+        if: github.event.inputs.dry-run != 'true'
+        run: |
+          git add ${{ matrix.package }}/package.json
+          git commit -m "chore(${{ matrix.package }}): release v${{ env.NEW_VERSION }}" || echo "No changes to commit"
+          git push origin ${{ github.ref_name }} || echo "Nothing to push"
+
+      - name: Create git tag
+        if: github.event.inputs.dry-run != 'true'
+        run: |
+          TAG_NAME="${{ matrix.package }}/v${{ env.NEW_VERSION }}"
+          git tag -a "$TAG_NAME" -m "Release ${{ matrix.package }} v${{ env.NEW_VERSION }}"
+          git push origin "$TAG_NAME"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }}
+
+      - name: Create GitHub Release
+        if: github.event.inputs.dry-run != 'true'
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ matrix.package }}/v${{ env.NEW_VERSION }}
+          release_name: ${{ matrix.package }} v${{ env.NEW_VERSION }}
+          body: |
+            Release of @zorihq/${{ matrix.package }} v${{ env.NEW_VERSION }}
+
+            ## Installation
+            ```bash
+            npm install @zorihq/${{ matrix.package }}@${{ env.NEW_VERSION }}
+            ```
+
+            See the [README](${{ github.server_url }}/${{ github.repository }}/tree/main/${{ matrix.package }}/README.md) for usage instructions.
+          draft: false
+          prerelease: false

PUBLISHING.md

@@ -0,0 +1,228 @@
+# Publishing Framework Libraries
+
+This document describes how to publish the ZoriHQ framework libraries to npm.
+
+## Prerequisites
+
+### 1. NPM Token
+
+You need to configure an NPM authentication token in GitHub Secrets:
+
+1. Create an npm account at https://www.npmjs.com/
+2. Generate an automation token: https://www.npmjs.com/settings/YOUR_USERNAME/tokens
+3. Add it to GitHub repository secrets as `NPM_TOKEN`
+
+### 2. Package Scope
+
+All packages are published under the `@zorihq` scope:
+- `@zorihq/react`
+- `@zorihq/nextjs`
+- `@zorihq/nextjs-server`
+- `@zorihq/vue`
+- `@zorihq/svelte`
+
+Ensure you have permission to publish to this scope on npm.
+
+## Publishing Workflow
+
+### Automatic Publishing via GitHub Actions
+
+The workflow `publish-packages.yml` handles building, versioning, and publishing packages to npm.
+
+#### Publish a Single Package
+
+1. Go to **Actions** → **Publish Framework Packages**
+2. Click **Run workflow**
+3. Select options:
+   - **Package**: Choose which package to publish (react, nextjs, nextjs-server, vue, svelte)
+   - **Version bump type**: Choose `patch`, `minor`, or `major`
+   - **Dry run**: Check this to test without actually publishing
+
+#### Publish All Packages
+
+1. Go to **Actions** → **Publish Framework Packages**
+2. Click **Run workflow**
+3. Select options:
+   - **Package**: Choose `all`
+   - **Version bump type**: Choose `patch`, `minor`, or `major`
+   - **Dry run**: Check this to test without actually publishing
+
+### What the Workflow Does
+
+1. **Checks out code** from the repository
+2. **Installs dependencies** for the selected package(s)
+3. **Verifies package files** to ensure everything is ready
+4. **Bumps version** according to your selection (patch, minor, major)
+5. **Publishes to npm** with public access
+6. **Commits version bump** back to the repository
+7. **Creates git tag** in format `{package}/v{version}` (e.g., `react/v1.0.1`)
+8. **Creates GitHub Release** with installation instructions
+
+## Manual Publishing (Local)
+
+If you need to publish manually from your local machine:
+
+### 1. Login to npm
+
+```bash
+npm login
+```
+
+### 2. Navigate to Package Directory
+
+```bash
+cd react  # or nextjs, nextjs-server, vue, svelte
+```
+
+### 3. Bump Version
+
+```bash
+npm version patch  # or minor, major
+```
+
+### 4. Publish
+
+```bash
+npm publish --access public
+```
+
+### 5. Tag and Push
+
+```bash
+git add package.json
+git commit -m "chore(react): release v1.0.1"
+git tag react/v1.0.1
+git push origin main --tags
+```
+
+## Version Bump Guidelines
+
+Follow semantic versioning:
+
+- **patch** (1.0.0 → 1.0.1): Bug fixes, small improvements
+- **minor** (1.0.0 → 1.1.0): New features, backward compatible
+- **major** (1.0.0 → 2.0.0): Breaking changes
+
+## Package Structure
+
+Each package is published with source files (TypeScript/TSX) to allow users' build systems to handle compilation:
+
+```
+@zorihq/react/
+├── index.tsx          # Main source file
+├── README.md          # Usage documentation
+├── package.json       # Package manifest
+└── tsconfig.json      # TypeScript config
+```
+
+## Verifying Published Packages
+
+After publishing, verify on npm:
+
+```bash
+npm view @zorihq/react
+npm view @zorihq/nextjs
+npm view @zorihq/nextjs-server
+npm view @zorihq/vue
+npm view @zorihq/svelte
+```
+
+Or visit:
+- https://www.npmjs.com/package/@zorihq/react
+- https://www.npmjs.com/package/@zorihq/nextjs
+- https://www.npmjs.com/package/@zorihq/nextjs-server
+- https://www.npmjs.com/package/@zorihq/vue
+- https://www.npmjs.com/package/@zorihq/svelte
+
+## Testing Before Publishing
+
+### Dry Run with GitHub Actions
+
+Always test with dry-run enabled first:
+
+1. Run the workflow with **dry-run: true**
+2. Check the workflow logs to see what would be published
+3. If everything looks good, run again with **dry-run: false**
+
+### Local Testing
+
+Test package locally before publishing:
+
+```bash
+cd react
+npm pack
+# This creates a .tgz file you can inspect or install locally
+```
+
+Install the packed version in a test project:
+
+```bash
+npm install /path/to/zorihq-react-1.0.0.tgz
+```
+
+## Troubleshooting
+
+### "You do not have permission to publish"
+
+- Ensure you're logged into the correct npm account
+- Ensure you have access to the `@zorihq` scope
+- Check that `NPM_TOKEN` secret is correctly configured
+
+### "Version already exists"
+
+- You're trying to publish a version that's already on npm
+- Bump the version first with `npm version patch/minor/major`
+
+### "Files not included in package"
+
+- Check the `files` field in `package.json`
+- Run `npm pack --dry-run` to see what would be included
+- Verify source files exist in the package directory
+
+## CI/CD Integration
+
+The workflow integrates with GitHub's CI/CD:
+
+- **On workflow_dispatch**: Manual trigger from GitHub Actions UI
+- **Permissions**: Requires `contents: write` and `packages: write`
+- **Matrix strategy**: Can publish multiple packages in parallel when `all` is selected
+
+## Post-Publishing
+
+After publishing:
+
+1. **Update documentation** if needed
+2. **Announce release** in relevant channels
+3. **Monitor npm** for download stats
+4. **Watch for issues** reported by users
+
+## Best Practices
+
+1. ✅ **Always use dry-run first** for new packages
+2. ✅ **Test locally** before publishing
+3. ✅ **Follow semantic versioning** strictly
+4. ✅ **Update README** with breaking changes
+5. ✅ **Tag releases** with descriptive names
+6. ✅ **Keep changelogs** updated
+7. ✅ **Coordinate releases** when updating multiple packages
+
+## Package URLs
+
+After publishing, packages are available at:
+
+- **npm**: `https://www.npmjs.com/package/@zorihq/{package-name}`
+- **GitHub**: `https://github.com/ZoriHQ/script/tree/main/{package-name}`
+- **Unpkg CDN**: `https://unpkg.com/@zorihq/{package-name}` (for bundled builds)
+
+## Support
+
+For issues with publishing:
+
+1. Check GitHub Actions logs for detailed error messages
+2. Verify npm credentials and permissions
+3. Review package.json configuration
+4. Test with `npm pack --dry-run` locally
+
+## License
+
+All packages are published under the MIT License.