@devwithbobby/loops 0.1.0

package/prds/CLAUDE.md

@@ -0,0 +1,408 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a **Convex component template** for building reusable Convex components. It uses:
+- **Bun** for package management, testing, and development
+- **Biome** for linting and formatting
+- **convex-test** for testing Convex functions
+- TypeScript with strict mode enabled
+
+## Key Commands
+
+### Development
+```sh
+bun run dev                  # Start both backend and frontend (with build watcher)
+bun run dev:backend          # Start Convex dev server with live component sources and typechecking
+bun run dev:frontend         # Start example frontend (Bun.serve with hot reload)
+bun run build                # Build TypeScript for distribution
+bun run build:watch          # Watch and rebuild on changes
+```
+
+### Testing
+```sh
+bun test                     # Run all tests
+bun test --watch             # Watch mode for continuous testing
+bun test --coverage          # Generate code coverage reports
+bun test --bail              # Stop after first failure
+bun test -t "pattern"        # Filter tests by name pattern
+CLAUDECODE=1 bun test        # AI-friendly quiet output (only shows failures)
+```
+
+### Linting and Formatting
+```sh
+bun run lint                 # Lint the codebase (Biome)
+bun run lint:fix             # Auto-fix linting issues
+bun run format               # Format code with Biome
+bun run check                # Run both lint and format checks
+bun run check:fix            # Auto-fix both lint and format issues
+```
+
+### Versioning and Releases
+```sh
+bun run changeset            # Add a new changeset (run when making user-facing changes)
+bun run ci:version           # Update versions and changelogs (usually automated by GitHub Actions)
+bun run ci:publish           # Publish to npm (usually automated by GitHub Actions)
+```
+
+## Project Structure
+
+```
+src/
+  component/               # The Convex component source code
+    convex.config.ts       # Component configuration (exported via package.json)
+    schema.ts              # Convex schema definition
+    lib.ts                 # Component functions (queries, mutations)
+    _generated/            # Auto-generated Convex types (gitignored)
+
+  client/                  # Client library (runs in app context, not component)
+    index.ts               # Helper class for easier component interaction
+    types.ts               # Type utilities for component API
+
+  react/                   # React hooks and components (optional)
+    index.ts               # React hooks for using the component
+
+test/
+  component/               # Component tests (separate from source to avoid bundling)
+    setup.test.ts          # Test setup with module auto-discovery
+    *.test.ts              # Unit tests for the component
+
+  client/                  # Client library tests
+    setup.test.ts          # Test setup that registers the component
+    *.test.ts              # Unit tests for the client library
+
+example/
+  convex/                  # Example app that uses the component
+    convex.config.ts       # Example app configuration that imports the component
+    schema.ts              # Example app schema
+    example.ts             # Example usage of the client library
+    _generated/            # Auto-generated Convex types (gitignored)
+
+  src/                     # Example frontend (Bun.serve + React)
+    index.tsx              # Bun server with hot reload
+    frontend.tsx           # React entry point
+    App.tsx                # Main React component
+```
+
+## Architecture
+
+### Convex Component Pattern
+This project follows the **Convex component architecture** with a three-layer structure:
+
+1. **Component Layer** (`src/component/`):
+   - Defines the component with `defineComponent("loopsComponent")`
+   - Contains the actual Convex functions (queries, mutations, actions)
+   - Has isolated tables, file storage, and scheduled functions
+   - Exported via package.json `"./convex.config"` with `@convex-dev/component-source` condition
+
+2. **Client Library Layer** (`src/client/`):
+   - Runs in the **app context** (not the component)
+   - Provides a helper class that wraps component API calls
+   - Can access `process.env` and `ctx.auth` from the app
+   - Exported via package.json `"."` (main entry point)
+   - Example: `LoopsComponent` class with `.add()` and `.count()` methods
+
+3. **React Layer** (`src/react/`):
+   - Optional React hooks and components
+   - Uses the client library internally
+   - Provides optimistic updates and loading states
+   - Exported via package.json `"./react"`
+   - Example: `useLoopsComponent()` hook
+
+**Usage Flow**:
+```typescript
+// 1. App mounts the component (example/convex/convex.config.ts)
+import component from "robertalv/loops-component/convex.config"
+app.use(component)
+
+// 2. App creates client wrapper (example/convex/example.ts)
+import { LoopsComponent } from "robertalv/loops-component"
+const counter = new LoopsComponent(components.loopsComponent)
+export const { add, count } = counter.api()
+
+// 3. React component uses the hook (example/src/App.tsx)
+import { useLoopsComponent } from "robertalv/loops-component/react"
+const { count, add } = useLoopsComponent(api.example, "myCounter")
+```
+
+### Testing Pattern
+This project uses `convex-test` with Bun's test runner. **Tests are kept separate from the component source** to prevent Convex from trying to bundle them during development.
+
+#### Component Tests (`test/component/`)
+Tests the component functions in isolation.
+
+**Setup** (`test/component/setup.test.ts`):
+- Auto-discovers all `.ts` files from `src/component/` using `Bun.Glob`
+- Creates a `modules` map for convex-test
+- Exports a `convexTest()` helper function
+- Preloaded by Bun (configured in `bunfig.toml`)
+
+**Example**:
+```ts
+import { test, expect } from "bun:test";
+import { api } from "../../src/component/_generated/api";
+import { convexTest } from "./setup.test";
+
+test("component function works", async () => {
+  const t = convexTest();
+  const result = await t.query(api.lib.greet, { name: "Alice" });
+  expect(result).toBe("Hello, Alice!");
+});
+```
+
+#### Client Library Tests (`test/client/`)
+Tests the client library that wraps the component. This is more complex because it requires **registering the component**.
+
+**Setup** (`test/client/setup.test.ts`):
+- Auto-discovers client test files from `test/client/`
+- Auto-discovers component files from `src/component/`
+- Exports `initConvexTest()` that creates a test instance and registers the component
+- Exports a mock `components` object for type-safe testing
+
+**Example**:
+```ts
+import { test, expect } from "bun:test";
+import { LoopsComponent } from "../../src/client/index.js";
+import { components, initConvexTest } from "./setup.test.js";
+
+test("client library works", async () => {
+  const t = initConvexTest();
+  const counter = new LoopsComponent(components.loopsComponent);
+
+  await t.run(async (ctx) => {
+    await counter.add(ctx, "test");
+    const count = await counter.count(ctx, "test");
+    expect(count).toBe(1);
+  });
+});
+```
+
+**Key difference**: Client tests use `t.registerComponent()` to mount the component within the test environment, simulating the real app usage pattern.
+
+### Example App Frontend
+The example app uses **Bun.serve** with HTML imports for a lightweight development experience.
+
+**Architecture**:
+- `example/src/index.tsx` - Bun server that serves HTML with hot reload
+- `example/src/frontend.tsx` - React entry point that bootstraps the app
+- `example/src/App.tsx` - Main React component using the component hooks
+
+**Key features**:
+- HTML files can directly import `.tsx` files (no bundler config needed)
+- Hot module reloading via `bun --hot`
+- Tailwind CSS via `bun-plugin-tailwind`
+- Convex environment variables automatically passed through
+
+**Running the frontend**:
+```sh
+bun run dev:frontend  # or: cd example && bun --hot src/index.tsx
+```
+
+## Code Style
+
+### Biome Configuration
+- **Indentation**: Tabs (not spaces)
+- **Quotes**: Double quotes for JavaScript/TypeScript
+- **Imports**: Auto-organized via Biome assist
+- **Ignores**: `_generated` directories are excluded from linting/formatting
+
+### TypeScript Configuration
+- Strict mode enabled with additional checks:
+  - `noUncheckedIndexedAccess: true`
+  - `noImplicitOverride: true`
+  - `noFallthroughCasesInSwitch: true`
+- Module resolution: `bundler` mode
+- JSX: `react-jsx` (automatic runtime)
+
+## Package Exports Configuration
+
+The `package.json` defines three entry points using conditional exports:
+
+```json
+{
+  "exports": {
+    ".": {
+      "@convex-dev/component-source": "./src/client/index.ts",
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./convex.config": {
+      "@convex-dev/component-source": "./src/component/convex.config.ts",
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./react": {
+      "@convex-dev/component-source": "./src/react/index.ts",
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    }
+  }
+}
+```
+
+**`@convex-dev/component-source` condition**:
+- Used during development with `--live-component-sources` flag
+- Points directly to TypeScript source files for hot reloading
+- Bypasses the built `dist/` directory for faster iteration
+
+**Why this matters**:
+- Production: Apps install the package and use built `.js` files from `dist/`
+- Development: The `--live-component-sources` flag makes Convex use `.ts` files directly
+- Type checking: TypeScript uses the `.d.ts` files from `dist/`
+
+## Important Notes
+
+- **Generated files**: Never edit files in `_generated/` directories - they are auto-generated by Convex
+- **Test files**: Place all test files in `test/component/` or `test/client/` directories (separate from `src/`) to prevent Convex from bundling them during development
+- **Component name**: Currently set to `"loopsComponent"` in convex.config.ts - change this for your component
+- **Live reloading**: The `--live-component-sources` flag enables hot-reloading during development
+- **Build exclusion**: Test files are excluded from the TypeScript build via `tsconfig.build.json`
+- **Client vs Component**: Remember that `src/client/` runs in the app context and can access env vars, while `src/component/` is isolated
+
+## Release Workflow (Changesets)
+
+This project uses [Changesets](https://github.com/changesets/changesets) for versioning and publishing automation.
+
+### When to Add a Changeset
+
+Add a changeset whenever you make user-facing changes:
+- ✅ New features (minor bump)
+- ✅ Bug fixes (patch bump)
+- ✅ Breaking changes (major bump)
+- ✅ API changes
+- ✅ Dependency updates that affect consumers
+
+Don't add a changeset for:
+- ❌ Documentation-only changes
+- ❌ Test-only changes
+- ❌ Internal refactoring with no API changes
+- ❌ CI/build configuration updates
+- ❌ Dev dependency updates
+
+### Adding a Changeset (For Contributors)
+
+1. Make your code changes
+2. Run the changeset command:
+   ```sh
+   bun run changeset
+   ```
+3. Follow the prompts:
+   - Select version bump type (patch, minor, or major)
+   - Write a summary of your changes
+4. A markdown file will be created in `.changeset/` directory
+5. Commit both your code changes AND the changeset file:
+   ```sh
+   git add .
+   git commit -m "feat: your feature description"
+   ```
+
+**Changeset Summary Guidelines:**
+- Write clear, concise descriptions
+- Focus on **what** changed and **why**
+- Include migration instructions for breaking changes
+- Use markdown formatting for readability
+
+**Example changeset file** (`.changeset/brave-lions-dance.md`):
+```markdown
+---
+"robertalv/loops-component": minor
+---
+
+Added `useResetCounter` hook for resetting counter values.
+
+You can now reset counters to zero:
+\`\`\`tsx
+const resetCounter = useResetCounter();
+await resetCounter("myCounter");
+\`\`\`
+```
+
+### Automated Release Process
+
+The release workflow is fully automated via GitHub Actions:
+
+1. **Developer adds changeset** and pushes to a feature branch
+2. **PR is created** → `test-and-lint.yml` workflow runs
+3. **PR is merged to main** → `release.yml` workflow runs
+4. **Release workflow detects changesets** and creates a "Version Packages" PR
+5. **Version PR is reviewed** → Check version bumps and CHANGELOG updates
+6. **Version PR is merged** → Package is automatically published to npm
+7. **GitHub release is created** with release notes
+
+### Manual Release (If Needed)
+
+If you need to publish manually (bypassing automation):
+
+```sh
+# 1. Update versions and changelogs from all changesets
+bun run ci:version
+
+# 2. Review changes to package.json and CHANGELOG.md
+git diff
+
+# 3. Commit the version changes
+git add .
+git commit -m "chore: version packages"
+git push
+
+# 4. Publish to npm (runs tests, build, and validation)
+bun run ci:publish
+```
+
+### Configuration Files
+
+- **`.changeset/config.json`**: Changesets configuration
+  - `access: "public"` - Package is published publicly to npm
+  - `changelog: "@changesets/changelog-github"` - Generates changelogs with PR links and contributor attribution
+  - `baseBranch: "main"` - Git branch for comparisons
+
+- **`.github/workflows/release.yml`**: GitHub Actions workflow for automated releases
+  - Triggers on push to `main` branch
+  - Creates version PRs when changesets exist
+  - Publishes to npm when version PR is merged
+  - Requires `NPM_TOKEN` secret in repository settings
+
+### Setting Up NPM Publishing (One-Time Setup)
+
+For the automated release workflow to publish packages, you need to configure an npm token:
+
+1. Go to [npmjs.com](https://npmjs.com) → Account Settings → Access Tokens
+2. Generate a new **Automation** token (bypasses 2FA for CI/CD)
+3. Copy the token
+4. In GitHub repository: Settings → Secrets and variables → Actions
+5. Create new secret named `NPM_TOKEN` with the token value
+6. Ensure GitHub Actions has write permissions:
+   - Settings → Actions → General → Workflow permissions
+   - Select "Read and write permissions"
+   - Check "Allow GitHub Actions to create and approve pull requests"
+
+### Viewing Published Versions
+
+After publishing:
+- **npm**: `https://www.npmjs.com/package/robertalv/loops-component`
+- **GitHub Releases**: `https://github.com/robertalv/loops-component/releases`
+- **Changelog**: `CHANGELOG.md` in the repository root
+
+### Troubleshooting
+
+**Changesets not detected?**
+- Ensure `.changeset/` files are committed and pushed
+- Check that changeset files have `.md` extension
+- Verify YAML frontmatter is properly formatted
+
+**Version PR not created?**
+- Check GitHub Actions tab for workflow errors
+- Ensure `GITHUB_TOKEN` has sufficient permissions
+- Verify no merge conflicts in the version PR
+
+**Publishing failed?**
+- Verify `NPM_TOKEN` is correctly set in repository secrets
+- Check npm token hasn't expired (max 90 days for granular tokens)
+- Ensure package name isn't already taken on npm
+- Run `bun run preversion` locally to catch test/lint failures
+
+**Multiple changesets in one PR?**
+- This is fine! All changesets will be consolidated in the version PR
+- Each changeset contributes to the overall version bump (highest semver wins)

package/prds/CONTRIBUTING.md

@@ -0,0 +1,274 @@
+# Contributing to Convex Component Template
+
+Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to this project.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+- [Coding Standards](#coding-standards)
+- [Testing](#testing)
+- [Submitting Changes](#submitting-changes)
+- [Release Process](#release-process)
+
+## Code of Conduct
+
+By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.
+
+## Getting Started
+
+### Prerequisites
+
+- **Bun** (latest stable version)
+- **Node.js** 18+ (for Convex CLI)
+- **Git**
+
+### Setup
+
+1. Fork the repository on GitHub
+2. Clone your fork locally:
+   ```sh
+   git clone https://github.com/SamHoque/convex-component-template.git
+   cd convex-component-template
+   ```
+
+3. Install dependencies:
+   ```sh
+   bun install
+   ```
+
+4. Set up your Convex dev environment:
+   ```sh
+   bun run dev:backend
+   ```
+
+5. In another terminal, run the example app:
+   ```sh
+   bun run dev:frontend
+   ```
+
+## Development Workflow
+
+### Running the Dev Environment
+
+The project uses a multi-process development setup:
+
+```sh
+# Start all dev processes (backend, frontend, build watch)
+bun run dev
+
+# Or run individually:
+bun run dev:backend    # Convex dev server with live component sources
+bun run dev:frontend   # Example app with hot reload
+bun run build:watch    # TypeScript build in watch mode
+```
+
+### Making Changes
+
+1. Create a new branch for your feature or bugfix:
+   ```sh
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes following the [coding standards](#coding-standards)
+
+3. Add tests for your changes in `test/component/`
+
+4. Run the test suite:
+   ```sh
+   bun test
+   ```
+
+5. Run linting and formatting:
+   ```sh
+   bun run check:fix
+   ```
+
+6. Commit your changes with a descriptive message following [Conventional Commits](https://www.conventionalcommits.org/):
+   ```sh
+   git commit -m "feat: add new counter increment limit"
+   ```
+
+### Commit Message Format
+
+We use conventional commit messages with gitmoji:
+
+- `✨ feat:` - New features
+- `🐛 fix:` - Bug fixes
+- `📝 docs:` - Documentation changes
+- `🎨 style:` - Code style/formatting changes
+- `♻️ refactor:` - Code refactoring
+- `✅ test:` - Test additions or updates
+- `🔧 chore:` - Build process or auxiliary tool changes
+- `⚡️ perf:` - Performance improvements
+- `👷 ci:` - CI/CD changes
+
+## Coding Standards
+
+### TypeScript
+
+- Use **strict mode** TypeScript
+- Enable all recommended checks
+- Avoid `any` types - use proper typing
+- Use `const` over `let` where possible
+
+### Code Style
+
+We use **Biome** for linting and formatting:
+
+- **Indentation**: Tabs (not spaces)
+- **Quotes**: Double quotes for strings
+- **Line length**: 100 characters (recommended)
+- **Semicolons**: Required
+
+Run the following before committing:
+
+```sh
+# Check for issues
+bun run check
+
+# Auto-fix issues
+bun run check:fix
+```
+
+### File Organization
+
+- **Component source**: `src/component/`
+- **Tests**: `test/component/` (separate from source to avoid bundling)
+- **React hooks**: `src/react/`
+- **Client utilities**: `src/client/`
+- **Example app**: `example/`
+
+### Naming Conventions
+
+- **Files**: camelCase for source files, kebab-case for config files
+- **Functions**: camelCase
+- **Components**: PascalCase (React)
+- **Constants**: UPPER_SNAKE_CASE
+- **Types/Interfaces**: PascalCase
+
+## Testing
+
+### Writing Tests
+
+Place all test files in `test/component/` directory:
+
+```typescript
+import { test, expect } from "bun:test";
+import { api } from "../../src/component/_generated/api";
+import { convexTest } from "./setup.test";
+
+test("my query works", async () => {
+	const t = convexTest();
+	const result = await t.query(api.lib.myQuery, { arg: "value" });
+	expect(result).toBe("expected");
+});
+```
+
+### Running Tests
+
+```sh
+# Run all tests
+bun test
+
+# Watch mode
+bun test --watch
+
+# With coverage
+bun test --coverage
+
+# Filter by name
+bun test -t "pattern"
+
+# Stop on first failure
+bun test --bail
+```
+
+### Testing Authenticated Scenarios
+
+```typescript
+test("authenticated query", async () => {
+	const t = convexTest();
+	const asUser = t.withIdentity({ subject: "user123" });
+	const result = await asUser.query(api.lib.userQuery, {});
+	expect(result).toBeDefined();
+});
+```
+
+## Submitting Changes
+
+### Pull Request Process
+
+1. Ensure all tests pass: `bun test`
+2. Ensure linting passes: `bun run check`
+3. Ensure TypeScript compiles: `bun run typecheck`
+4. Ensure package exports are correct: `bun run attw`
+5. Update documentation if needed
+6. Push your branch to your fork
+7. Open a Pull Request against the `main` branch
+8. Fill out the PR template with:
+   - Description of changes
+   - Related issue numbers
+   - Testing performed
+   - Breaking changes (if any)
+
+### PR Review Process
+
+- At least one maintainer approval is required
+- All CI checks must pass
+- Code must follow the project's coding standards
+- Tests must be included for new features
+
+### What Happens After Your PR is Merged
+
+- Your changes will be included in the next release
+- The CHANGELOG will be updated
+- You'll be credited as a contributor
+
+## Release Process
+
+This section is for maintainers.
+
+### Version Bumping
+
+The project uses npm version scripts:
+
+```sh
+# Alpha release (pre-release)
+bun run alpha
+
+# Patch release (0.1.0 -> 0.1.1)
+bun run release
+
+# Manual version bump
+npm version [major|minor|patch]
+```
+
+### What Happens During Release
+
+1. `preversion`: Runs tests, linting, typecheck, and package validation
+2. `version`: Updates version, opens CHANGELOG.md for editing, formats it
+3. `postversion`: Pushes changes and tags to GitHub
+
+### Publishing
+
+Publishing happens automatically after version bump:
+
+```sh
+# For alpha releases
+npm publish --tag alpha
+
+# For stable releases
+npm publish
+```
+
+## Questions?
+
+If you have questions, please:
+
+- Check existing issues and discussions
+- Open a new issue for bugs
+- Start a discussion for questions
+
+Thank you for contributing!