{"id":50439984,"url":"https://github.com/alp82/aistack","last_synced_at":"2026-06-17T10:01:11.097Z","repository":{"id":333216922,"uuid":"1127897925","full_name":"alp82/aistack","owner":"alp82","description":"Like Stackshare but for AI","archived":false,"fork":false,"pushed_at":"2026-06-13T07:55:57.000Z","size":12752,"stargazers_count":17,"open_issues_count":2,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-13T08:20:35.067Z","etag":null,"topics":["agentic-workflow","ai","ai-agents","coding","community","stack"],"latest_commit_sha":null,"homepage":"https://aistack.to","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alp82.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-04T20:03:38.000Z","updated_at":"2026-06-13T07:56:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alp82/aistack","commit_stats":null,"previous_names":["alp82/aistack"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alp82/aistack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alp82%2Faistack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alp82%2Faistack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alp82%2Faistack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alp82%2Faistack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alp82","download_url":"https://codeload.github.com/alp82/aistack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alp82%2Faistack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34443239,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-workflow","ai","ai-agents","coding","community","stack"],"created_at":"2026-05-31T19:00:18.918Z","updated_at":"2026-06-17T10:01:11.088Z","avatar_url":"https://github.com/alp82.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# AI Stack\n\n\u003cdiv align=\"center\"\u003e\n\n[![Live Page](https://img.shields.io/badge/Live_Page-aistack.to-blue?style=for-the-badge\u0026logo=web)](https://aistack.to)\n\n[![AI Stack Demo](public/aistack-demo.gif)](https://aistack.to)\n\n**A curated platform for discovering, comparing, and sharing AI technology stacks**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![React](https://img.shields.io/badge/React-20232A?logo=react\u0026logoColor=61DAFB)](https://reactjs.org/)\n[![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-38B2AC?logo=tailwind-css\u0026logoColor=white)](https://tailwindcss.com/)\n\n[![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord\u0026logoColor=white\u0026style=for-the-badge)](https://discord.gg/5y4fpyahaF)\n[![Reddit](https://img.shields.io/badge/Reddit-FF4500?logo=reddit\u0026logoColor=white\u0026style=for-the-badge)](https://www.reddit.com/r/aistackcommunity/)\n\n\u003c/div\u003e\n\n## 🎯 Purpose\n\nAI Stack is a web application designed to help developers and teams discover, compare, and share AI technology stacks. Whether you're building a new AI-powered application or looking to optimize your existing stack, AI Stack provides a curated collection of tools, frameworks, and libraries to make informed decisions.\n\n## ✨ Features\n\n- **Discover** AI tools and frameworks organized by stack\n- **Compare** different stacks side by side and cut costs for your own usage\n- **Share** your own AI stacks with the community\n- **Add Missing Tools** inline during stack creation or in batch mode\n- **Stay Updated** with the latest AI technology trends\n- **Authentication** via email/password and Google SSO\n\n## ⚙️ How It Works\n\nAI Stack has two surfaces that work together:\n\n1. **The web app** ([aistack.to](https://aistack.to)) — where you browse stacks, compare tools, and publish your own setups. Each stack can group multiple **projects**, and each project holds your actual AI configuration files (prompts, rules, skills, MCP servers).\n\n2. **The CLI** (`@use-aistack/cli`) — a small tool that bridges your local filesystem with your stack on the web. It scans your project for AI config files and uploads them, or clones someone else's configs into your working directory. No manual copy-paste.\n\nTypical flow:\n\n- Sign up on the web app and create a stack.\n- Run `npx @use-aistack/cli collect` inside your repo to upload your `.cursorrules`, `CLAUDE.md`, `AGENTS.md`, skills, MCP configs, etc. to your stack.\n- Share the stack link. On another machine, run `npx @use-aistack/cli create` to write your stack's AI setup into the current directory.\n\n## 💻 CLI\n\nThe CLI is published to npm as [`@use-aistack/cli`](https://www.npmjs.com/package/@use-aistack/cli). Run it on-demand with `npx` — no install required:\n\n```sh\nnpx @use-aistack/cli \u003ccommand\u003e\n```\n\n### Commands\n\n#### `npx @use-aistack/cli login`\n\nAuthenticate with your AI Stack account via browser.\n\n```sh\nnpx @use-aistack/cli login\n```\n\n#### `npx @use-aistack/cli collect`\n\nScan the current project for AI config files and upload them to your stack on aistack.to.\n\n```sh\ncd your-project\nnpx @use-aistack/cli collect\n```\n\nDetects: `.cursorrules`, `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`, `mcp.json`, skill directories, prompts, and global configs (`~/.claude/`, `~/.cursor/`, etc).\n\n#### `npx @use-aistack/cli create`\n\nWrite your stack's AI config files into the current directory.\n\n```sh\nnpx @use-aistack/cli create\n```\n\n### Install globally (optional)\n\nIf you'd rather type `aistack` instead of `npx @use-aistack/cli` every time, install it globally:\n\n```sh\nnpm i -g @use-aistack/cli\n```\n\nThen the same commands become:\n\n```sh\naistack login\naistack collect\naistack create\n```\n\n---\n\n# Contributing\n\nThe rest of this document is for contributors working on the AI Stack web app or CLI.\n\n## 🛠 Tech Stack\n\n### Frontend\n- **Framework**: [TanStack Start](https://tanstack.com/start) - Full-stack React framework\n- **UI Library**: [React 19](https://react.dev/) - Latest React with concurrent features\n- **Styling**: [Tailwind CSS v4](https://tailwindcss.com/) - Utility-first CSS framework\n- **Icons**: [Lucide React](https://lucide.dev/) - Beautiful \u0026 consistent icons\n- **Animations**: [Motion](https://motion.dev/) \u0026 [GSAP](https://greensock.com/gsap/) - Smooth animations\n- **Components**: [Radix UI](https://www.radix-ui.com/) - Accessible component primitives\n\n### Backend \u0026 Data\n- **Backend**: [Convex](https://convex.dev/) - Serverless database and backend functions\n- **Authentication**: [Better Auth](https://better-auth.com/) - Modern authentication solution\n- **State Management**: [TanStack Query](https://tanstack.com/query) - Server state management\n- **Forms**: [TanStack Forms](https://tanstack.com/form) - Type-safe form handling\n\n### Development Tools\n- **Language**: [TypeScript](https://www.typescriptlang.org/) - Type-safe JavaScript\n- **Build Tool**: [Vite](https://vitejs.dev/) - Fast build tool and dev server\n- **Package Manager**: [pnpm](https://pnpm.io/) - Fast, disk space efficient package manager\n- **Linting/Formatting**: [Biome](https://biomejs.dev/) - All-in-one toolchain\n- **Testing**: [Vitest](https://vitest.dev/) - Fast unit testing framework\n\n### Analytics\n- **Analytics**: [PostHog](https://posthog.com/) - Product analytics suite\n\n## 📁 Project Structure\n\n```\naistack/              # Main web application\n├── convex/           # Convex backend functions \u0026 schema\n├── public/           # Static assets\n├── src/              # React application source\n│   ├── components/   # Shared UI primitives and cross-feature components\n│   ├── features/     # Feature-scoped modules (landing, stack-editor, etc.)\n│   ├── integrations/ # Third-party integrations\n│   └── routes/       # File-based routing\n└── README.md         # You are here\n```\n\n### Frontend Architecture Notes\n\n- Route files should stay composition-focused (data fetch + section orchestration).\n- Landing page is organized under `src/features/landing/*`.\n- Stack editor is organized under `src/features/stack-editor/*` with:\n  - section components in `sections/*`\n  - reducer/selectors/hooks in `state/*`\n  - status computation in `editor-status.ts`\n- Reusable visual wrappers live under `src/components/system/*`.\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- **Node.js** (v18 or higher)\n- **pnpm** (recommended) or npm\n- **Git**\n\n### Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/alp82/aistack.git\n   cd aistack\n   ```\n\n2. **Install dependencies**\n   ```bash\n   pnpm install\n   ```\n\n3. **Set up environment variables**\n   ```bash\n   # Copy the example environment file\n   cp .env.example .env.local\n   \n   # Configure your environment variables\n   # VITE_CONVEX_URL and CONVEX_DEPLOYMENT are required\n   ```\n\n4. **Initialize Convex**\n   ```bash\n   pnpm convex dev\n   ```\n   This will automatically set up your Convex deployment and update your environment variables.\n\n5. **Start the development server**\n   ```bash\n   pnpm dev\n   ```\n\n   The application will be available at:\n   - Frontend: http://localhost:3019\n   - Convex Dashboard: http://localhost:3210\n\n## 📜 Available Scripts\n\n```bash\n# Development\npnpm dev          # Start development server\npnpm convex dev   # Start Convex backend server\n\n# Building\npnpm build        # Build for production\npnpm preview      # Preview production build\n\n# Code Quality\npnpm lint         # Run Biome linter\npnpm format       # Format code with Biome\npnpm check        # Run all Biome checks\n\n# Testing\npnpm test         # Run unit tests with Vitest\n```\n\n## 🧪 Testing\n\nThe project uses [Vitest](https://vitest.dev/) for unit testing. Tests are located in the `src/**/__tests__` directories.\n\nVitest is configured in `vite.config.ts` with:\n\n- `test.environment = \"jsdom\"`\n- `test.setupFiles = [\"./src/test/setup.ts\"]`\n\n`src/test/setup.ts` loads `@testing-library/jest-dom/vitest` matchers for DOM assertions.\n\n```bash\n# Run all tests\npnpm test\n\n# Run a single test file\npnpm vitest run src/features/stack-editor/state/__tests__/editor-reducer.test.ts\n\n# Run tests in watch mode\npnpm test --watch\n\n# Generate coverage report\npnpm test --coverage\n```\n\n## 🎨 Adding Components\n\nThis project uses [Shadcn UI](https://ui.shadcn.com/) components. Add new components with:\n\n```bash\npnpm dlx shadcn@latest add [component-name]\n```\n\n## 📊 Development Notes\n\n- The development server runs on `http://localhost:3019`\n- The Convex backend runs on `http://localhost:3210`\n- Both servers should remain running during development\n- Use Chrome DevTools MCP for debugging and reviewing code updates\n- **Dev Admin Access**: In development mode, a \"Dev Admin Login\" button appears on the login page. It signs in as `dev-admin@example.com` with admin privileges. This requires the Convex env var `IS_DEV=true` to be set (email verification is also skipped when `IS_DEV=true`)\n\n## Database Migrations\n\nMigration scripts are located in `convex/migrations/`. Run them via the Convex Dashboard or CLI.\n\n### Running Migrations via Convex Dashboard\n\n1. Open your Convex Dashboard at https://dashboard.convex.dev\n2. Navigate to your project → **Functions** tab\n3. Find the migration function under `migrations/`\n4. Click on the function and use **Run Function** to execute it\n\n### Running Migrations via CLI\n\n```bash\n# Run an internal query (read-only, for previews)\nnpx convex run migrations/backup:exportStackDescriptions\n\n# Run an internal mutation (makes changes)\nnpx convex run migrations/populateShortIds:populateAllShortIds\n```\n\n### Available Migration Scripts\n\n#### `migrations/backup.ts` - Backup \u0026 Restore\n\n| Function | Type | Description |\n|----------|------|-------------|\n| `exportStackDescriptions` | Query | Export all stack descriptions as JSON backup |\n| `exportShortIdMappings` | Query | Export tool/model/bundle shortId mappings |\n| `restoreStackDescription` | Mutation | Restore a single stack from backup |\n| `restoreStackDescriptionsBatch` | Mutation | Restore multiple stacks from backup array |\n\n#### `migrations/populateShortIds.ts` - ShortId Population\n\n| Function | Type | Description |\n|----------|------|-------------|\n| `getMissingCounts` | Query | Check how many records are missing shortId |\n| `populateAllShortIds` | Mutation | Populate shortIds for all tools, models, bundles |\n| `populateToolShortIds` | Mutation | Populate shortIds for tools only |\n| `populateModelShortIds` | Mutation | Populate shortIds for models only |\n| `populateBundleShortIds` | Mutation | Populate shortIds for bundles only |\n\n#### `migrations/migrateStackDescriptions.ts` - Description Migration\n\n| Function | Type | Description |\n|----------|------|-------------|\n| `getStackCounts` | Query | Count stacks with legacy blocks (iconurl attributes) |\n| `dryRunMigration` | Query | Preview what would be migrated without changes |\n| `previewStackMigration` | Query | Preview migration for a single stack |\n| `migrateAllStackDescriptions` | Mutation | Run the actual migration on all stacks |\n\n### Migration Workflow\n\n**Before running migrations on production, always create a backup first!**\n\n```bash\n# Step 1: Backup existing stack descriptions\nnpx convex run migrations/backup:exportStackDescriptions \u003e backup-stacks.json\n\n# Step 2: Check how many records need shortId population\nnpx convex run migrations/populateShortIds:getMissingCounts\n\n# Step 3: Populate shortIds for tools, models, and bundles\nnpx convex run migrations/populateShortIds:populateAllShortIds\n\n# Step 4: Preview description migration (dry run)\nnpx convex run migrations/migrateStackDescriptions:dryRunMigration\n\n# Step 5: Run the actual description migration\nnpx convex run migrations/migrateStackDescriptions:migrateAllStackDescriptions\n```\n\n### Restoring from Backup\n\nIf something goes wrong, restore from your backup:\n\n```bash\n# For a single stack\nnpx convex run migrations/backup:restoreStackDescription \\\n  '{\"stackId\": \"k1234...\", \"description\": \"\u003cp\u003eOriginal content...\u003c/p\u003e\"}'\n\n# For multiple stacks (pass JSON array)\nnpx convex run migrations/backup:restoreStackDescriptionsBatch \\\n  '{\"backups\": [{\"stackId\": \"k1234...\", \"description\": \"...\"}]}'\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please read our contributing guidelines and submit pull requests to the main branch.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🔗 Links\n\n- [TanStack Documentation](https://tanstack.com)\n- [Convex Documentation](https://docs.convex.dev)\n- [Tailwind CSS](https://tailwindcss.com/docs)\n- [Better Auth](https://better-auth.com/docs)\n\n## 📞 Support\n\nIf you have any questions or need help, please open an issue on GitHub.\n\n---\n\n\u003cdiv align=\"center\"\u003e\nMade with ❤️ by Alper Ortac: https://x.com/alperortac\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falp82%2Faistack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falp82%2Faistack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falp82%2Faistack/lists"}