virastack 0.0.1 → 1.0.0

package/templates-i18n/tanstack/README.md

@@ -0,0 +1,204 @@
+<div align="center">
+
+<a href="https://github.com/virastack/start" target="_blank" rel="noreferrer">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/virastack/start/main/assets/logo-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/virastack/start/main/assets/logo-light.png">
+    <img src="https://raw.githubusercontent.com/virastack/start/main/assets/logo-light.png" alt="ViraStack Start" height="120" style="max-width: 100%;" />
+  </picture>
+</a>
+
+# ViraStack Start — TanStack Edition
+
+_The TanStack Start boilerplate that feels effortless._
+
+[![ViraStack TanStack](https://img.shields.io/badge/ViraStack-TanStack-%2300bba7)](https://virastack.com)
+[![npm version](https://img.shields.io/npm/v/virastack)](https://www.npmjs.com/package/virastack)
+[![npm downloads](https://img.shields.io/npm/dt/virastack)](https://www.npmjs.com/package/virastack)
+[![Node](https://img.shields.io/badge/node-%3E%3D20.9-339933?logo=node.js&logoColor=white)](package.json)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/virastack/start/actions/workflows/ci.yml/badge.svg)](https://github.com/virastack/start/actions/workflows/ci.yml)
+[![@virastack](https://img.shields.io/badge/-%40virastack-black?logo=x&logoColor=white)](https://x.com/virastack)
+
+</div>
+
+---
+
+**Docs:** [See the docs](https://www.virastack.com/)
+
+**Contents:** [Why](#why-virastack) · [Features](#features) · [Getting started](#getting-started) · [Environment](#environment-variables) · [Scripts](#scripts) · [Project structure](#project-structure) · [Customization](#customization) · [ViraStack AI](#virastack-ai) · [Deployment](#deployment)
+
+Production-grade TanStack Start starter with feature-sliced architecture, strict TypeScript, and a pre-configured [**ViraStack AI**](https://github.com/virastack/ai) layer — so you and your coding agents ship consistent code from day one.
+
+## Why ViraStack
+
+- **Opinionated, not opaque** — clear folder rules and placement conventions; nothing important is hidden behind magic
+- **Agent-ready by default** — `AGENTS.md`, Cursor rules, `llms.txt`, and design skills ship with every project
+- **Own your UI** — Base UI primitives in `components/ui` (shadcn-style), fully editable
+- **State triad** — TanStack Query (server), Zustand (client), nuqs (URL) — each with a dedicated job
+- **DX that sticks** — ESLint, Prettier, Knip, Husky, Commitlint, and GitHub Actions CI out of the box
+
+## Features
+
+**Included**
+
+- ⚡ **TanStack Start** — file-based TanStack Router, type-safe loaders, SSR
+- ⚛️ **React 19** + TypeScript strict (`noUncheckedIndexedAccess`)
+- 🎨 **Tailwind CSS 4** + Base UI primitives
+- 🔄 **TanStack Query** · **Zustand** · **nuqs**
+- 📋 **React Hook Form** + **Zod** — validated forms end to end
+- 🤖 **ViraStack AI** — agent context, scoped rules, design skills
+- ✅ **Quality built in** — ESLint, Prettier, Knip, Husky, Commitlint, CI (typecheck → lint → knip → build)
+
+**Optional / bring your own**
+
+- Auth, database, i18n, analytics, and monitoring — wire them in when you need them; the architecture is ready
+
+## Getting started
+
+**Quick Start & Setup:** Please follow the instructions in the main [ViraStack Start README](https://github.com/virastack/start#quick-start).
+
+Once your project is scaffolded, start the development server:
+
+```bash
+pnpm dev
+```
+
+Open [http://localhost:3000](http://localhost:3000). The home route renders `LandingPage` from `src/features/landing` — a full demo of the stack (theme toggle, TanStack Query, Zustand, Zod forms, nuqs). Delete that feature when you are ready to build.
+
+## Environment variables
+
+Validated in `src/env.ts`. Scaffolded projects already have `.env.local`.
+
+| Variable        | Scope  | Description                                                   |
+| :-------------- | :----- | :------------------------------------------------------------ |
+| `VITE_APP_URL`  | Public | Canonical app URL (default `http://localhost:3000`)           |
+| `VITE_APP_NAME` | Public | Product name shown in UI/metadata (default `ViraStack Start`) |
+
+`NODE_ENV` is set by Vite — do not define it manually. Add new vars in both `.env.example` and `src/env.ts`.
+
+## Scripts
+
+| Script                          | Description                                  |
+| :------------------------------ | :------------------------------------------- |
+| `dev`                           | Start the Vite + TanStack Start dev server   |
+| `build`                         | Production build                             |
+| `start` / `preview`             | Serve the production build                   |
+| `lint` / `lint:fix` / `lint:ci` | ESLint (+ format check in CI)                |
+| `format` / `format:check`       | Prettier                                     |
+| `typecheck`                     | `tsc --noEmit`                               |
+| `knip`                          | Find unused files, exports, and dependencies |
+
+CI runs the same gates: typecheck → lint → knip → build (see `.github/workflows/ci.yml`).
+
+## Project structure
+
+```
+src/
+├── routes/               # File-based TanStack Router routes
+├── features/
+│   └── landing/          # Demo feature (canonical folder layout)
+│       ├── api/
+│       ├── components/   # Hero, Features, Showcase, demos, LandingPage
+│       ├── constants/
+│       ├── data/
+│       ├── helpers/
+│       ├── hooks/
+│       ├── icons/        # Brand SVGs used only by the landing demo
+│       ├── schemas/
+│       ├── stores/
+│       ├── types/
+│       └── index.ts
+├── components/
+│   ├── ui/               # Base UI primitives (Button, Dialog, Tabs, …)
+│   ├── layout/           # Header, Footer (reusable chrome)
+│   └── shared/           # Cross-feature components (ThemeToggle, …)
+├── hooks/                # Shared hooks (promote via Rule of Three)
+├── stores/
+├── schemas/
+├── providers/
+├── lib/                  # api.ts, query-client.ts, utils
+├── config/
+├── constants/
+├── helpers/
+├── types/
+├── styles/
+├── integrations/         # Framework integrations (TanStack Query)
+├── router.tsx
+├── start.ts              # Global request middleware (security headers)
+└── env.ts
+```
+
+The bundled `landing` feature follows the ViraStack AI feature tree and is meant to be deleted when you start building.
+
+**Quick start (strip the demo)**
+
+1. Delete `src/features/landing`
+2. Replace `src/routes/index.tsx` with your own route
+3. Keep `components/layout` Header/Footer if you still want site chrome — pass `links` only when you need nav items
+
+**Rules of thumb**
+
+- Default scope is `features/[feature]/` — promote to global `src/` only when a second feature needs it
+- No cross-feature imports; share via `components/`, `lib/`, `hooks/`, etc.
+- Path aliases are mandatory; parent-relative imports (`../`) are forbidden
+
+See [`docs/architecture-guide.md`](docs/architecture-guide.md) for placement rules and import conventions.
+
+## Customization
+
+Search the repo for `FIXME:` to find the first things to own:
+
+| File                          | What to change                    |
+| :---------------------------- | :-------------------------------- |
+| `src/config/site.config.ts`   | Site name, description, metadata  |
+| `vite.config.ts`              | Vite / TanStack Start options     |
+| `src/start.ts`                | Global request middleware/headers |
+| `src/lib/api.ts`              | Auth header / API client wiring   |
+| `src/env.ts` + `.env.example` | New environment variables         |
+| `public/`                     | Favicon and static assets         |
+
+You own every file — trim demos, rename features, keep only what you need.
+
+## ViraStack AI
+
+Developed with [**ViraStack AI**](https://github.com/virastack/ai) — an AI-native architecture kit that ships agent context into every project:
+
+| File              | Purpose                          |
+| :---------------- | :------------------------------- |
+| `AGENTS.md`       | Agent operating guide            |
+| `CLAUDE.md`       | Claude Code entry point          |
+| `.cursor/rules/`  | Scoped coding rules              |
+| `public/llms.txt` | Machine-readable project summary |
+| `.agents/skills/` | Design-taste skills              |
+
+Install or refresh rules: `npx @virastack/ai init`
+
+## Deployment
+
+Works with [Netlify](https://www.netlify.com/), [Cloudflare](https://developers.cloudflare.com/), Nitro, Railway, or any Node host:
+
+1. Push the repo and import the project
+2. Set `VITE_APP_URL` and `VITE_APP_NAME` from `.env.example`
+3. Deploy — `pnpm build` / `pnpm start` work on any Node host that can serve the Vite output
+
+## Philosophy
+
+- Minimal surface, strong conventions
+- Agent-first documentation lives next to the code
+- Own your UI and architecture — no locked black boxes
+- Production-ready DX without forcing auth/db opinions until you need them
+
+## Contributing
+
+Ideas and bug reports welcome — open an [issue](https://github.com/virastack/start/issues).
+
+PRs that improve DX, architecture docs, or the landing showcase are especially appreciated.
+
+---
+
+<div align="center">
+
+Bootstrapped with [**ViraStack Start**](https://github.com/virastack/start) · Built by <a href="https://omergulcicek.com">Ömer Gülçiçek</a> · <a href="LICENSE">MIT Licensed</a>
+
+</div>

package/templates-i18n/tanstack/commitlint.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  extends: ["@commitlint/config-conventional"],
+  rules: {
+    "body-max-line-length": [0, "always"],
+  },
+};

package/templates-i18n/tanstack/eslint.config.js

@@ -0,0 +1,29 @@
+//  @ts-check
+
+import { tanstackConfig } from "@tanstack/eslint-config";
+
+export default [
+  ...tanstackConfig,
+  {
+    rules: {
+      "import/no-cycle": "off",
+      "import/order": "off",
+      "sort-imports": "off",
+      "@typescript-eslint/array-type": "off",
+      "@typescript-eslint/require-await": "off",
+      "pnpm/json-enforce-catalog": "off",
+    },
+  },
+  {
+    ignores: [
+      "eslint.config.js",
+      "knip.config.js",
+      "commitlint.config.js",
+      "src/routeTree.gen.ts",
+      "src/paraglide/**",
+      "dist/**",
+      ".tanstack/**",
+      ".output/**",
+    ],
+  },
+];

package/templates-i18n/tanstack/knip.config.js

@@ -0,0 +1,26 @@
+/** @type {import('knip').KnipConfig} */
+const config = {
+  entry: ["src/router.tsx", "src/start.ts", "src/server.ts", "src/routes/**/*.{ts,tsx}"],
+  project: ["src/**/*.{ts,tsx,js,jsx}"],
+  ignore: [
+    "src/components/ui/**",
+    // Shared-layer barrels reserved for Rule-of-Three promotions
+    "src/hooks/index.ts",
+    "src/stores/index.ts",
+    "src/schemas/index.ts",
+    "src/constants/index.ts",
+    // Domain-layer barrels
+    "src/features/**/data/index.ts",
+    "src/features/**/data/*.data.tsx",
+    "src/features/**/schemas/index.ts",
+  ],
+  ignoreDependencies: ["tailwindcss", "tw-animate-css"],
+  rules: {
+    dependencies: "error",
+    exports: "warn",
+    types: "warn",
+    files: "warn",
+  },
+};
+
+module.exports = config;

package/templates-i18n/tanstack/messages/en.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://inlang.com/schema/inlang-message-format",
+  "hero_badge": "Premium UI/UX · Agent-ready · Zero bloat",
+  "hero_title_1": "ViraStack",
+  "hero_title_2": "Start",
+  "hero_desc_1": "Built with ",
+  "hero_desc_2": ", ",
+  "hero_desc_3": ", and ",
+  "hero_desc_4": " - wired together with ",
+  "hero_desc_5": ", ",
+  "hero_desc_6": ", and ",
+  "hero_desc_7": " so you can ship a polished product from day one.",
+  "github": "Star on GitHub",
+  "theme": "Theme",
+  "language": "Language",
+  "features_title": "Features",
+  "features_subtitle": "Everything you need to build a modern web application, already configured with the best practices.",
+  "feature_1_title": "TanStack Start",
+  "feature_1_desc": "Full-stack React framework with SSR, streaming, and powerful routing features.",
+  "feature_2_title": "Type-Safe Everything",
+  "feature_2_desc": "End-to-end type safety from environment variables to API responses with TypeScript and Zod.",
+  "feature_3_title": "TanStack Query",
+  "feature_3_desc": "Server-state caching and synchronization, plus URL state via nuqs - all wired and ready to use.",
+  "feature_4_title": "Tailwind & shadcn/ui",
+  "feature_4_desc": "shadcn/ui patterns on Base UI primitives - Tailwind CSS v4, accessible, and fully yours to own.",
+  "feature_5_title": "React Hook Form",
+  "feature_5_desc": "Performant, flexible, and extensible forms with easy-to-use validation integration.",
+  "feature_6_title": "ViraStack AI",
+  "feature_6_desc": "Pre-configured agent context - coding rules, design skills, and AGENTS.md so any AI assistant matches this codebase.",
+  "showcase_title": "Showcase",
+  "showcase_subtitle": "Experience the seamless integration of UI components and state management.",
+  "showcase_project_title": "New Project",
+  "showcase_project_desc_1": "Validated forms with ",
+  "showcase_project_desc_2": " and ",
+  "showcase_project_desc_3": ".",
+  "showcase_state_title": "Global State",
+  "showcase_state_desc_1": "Shared client state managed with ",
+  "showcase_state_desc_2": ".",
+  "showcase_footer_license": "© {year} {name}. MIT Licensed.",
+  "showcase_footer_built": "Last updated on {date}.",
+  "users_title": "Recent Users",
+  "users_desc_1": "Fetch and cache data with ",
+  "users_desc_2": ", synced to the URL via ",
+  "users_desc_3": ".",
+  "users_search": "Search users...",
+  "users_refresh": "Refresh",
+  "users_refreshing": "Refreshing...",
+  "users_col_user": "User",
+  "users_col_city": "City",
+  "users_error_status": "Request failed with status {status}.",
+  "users_error_network": "Failed to load users. Check your network connection.",
+  "users_empty": "No users found.",
+  "project_label": "Project Name",
+  "project_placeholder": "virastack-app",
+  "project_desc": "Use 3–50 characters for the project name.",
+  "project_submit": "Create Project",
+  "project_submitting": "Creating…",
+  "project_success": "Created project: {name}",
+  "project_validation_min": "Project name must be at least 3 characters.",
+  "project_validation_max": "Project name must be at most 50 characters.",
+  "cart_item_name": "Cotton T-Shirt",
+  "cart_item_variant": "White / XL",
+  "cart_item_total": "Total",
+  "cart_clear": "Clear"
+}

package/templates-i18n/tanstack/messages/tr.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://inlang.com/schema/inlang-message-format",
+  "hero_badge": "Premium UI/UX · Yapay zeka uyumlu · Sıfır fazlalık",
+  "hero_title_1": "ViraStack",
+  "hero_title_2": "Start",
+  "hero_desc_1": "",
+  "hero_desc_2": ", ",
+  "hero_desc_3": " ve ",
+  "hero_desc_4": " ile oluşturuldu - ilk günden mükemmel bir ürün çıkarabilmeniz için ",
+  "hero_desc_5": ", ",
+  "hero_desc_6": " ve ",
+  "hero_desc_7": " ile birbirine bağlandı.",
+  "github": "GitHub'da Yıldızla",
+  "theme": "Tema",
+  "language": "Dil",
+  "features_title": "Özellikler",
+  "features_subtitle": "Modern bir web uygulaması oluşturmak için ihtiyacınız olan her şey, en iyi uygulamalarla önceden yapılandırıldı.",
+  "feature_1_title": "TanStack Start",
+  "feature_1_desc": "SSR, akış ve güçlü yönlendirme özelliklerine sahip tam yığın React framework'ü.",
+  "feature_2_title": "Her Şey Tip Güvenli",
+  "feature_2_desc": "TypeScript ve Zod ile ortam değişkenlerinden API yanıtlarına kadar uçtan uca tip güvenliği.",
+  "feature_3_title": "TanStack Query",
+  "feature_3_desc": "Sunucu durumu önbelleğe alma ve senkronizasyon, artı nuqs aracılığıyla URL durumu - hepsi bağlı ve kullanıma hazır.",
+  "feature_4_title": "Tailwind ve shadcn/ui",
+  "feature_4_desc": "Base UI temel öğeleri üzerinde shadcn/ui desenleri - Tailwind CSS v4, erişilebilir ve tamamen size ait.",
+  "feature_5_title": "React Hook Form",
+  "feature_5_desc": "Kullanımı kolay doğrulama entegrasyonuna sahip yüksek performanslı, esnek ve genişletilebilir formlar.",
+  "feature_6_title": "ViraStack AI",
+  "feature_6_desc": "Önceden yapılandırılmış ajan bağlamı - herhangi bir AI asistanının bu kod tabanıyla eşleşmesi için kodlama kuralları, tasarım becerileri ve AGENTS.md.",
+  "showcase_title": "Vitrin",
+  "showcase_subtitle": "Kullanıcı arayüzü bileşenleri ile durum yönetiminin kusursuz entegrasyonunu deneyimleyin.",
+  "showcase_project_title": "Yeni Proje",
+  "showcase_project_desc_1": "",
+  "showcase_project_desc_2": " ve ",
+  "showcase_project_desc_3": " ile doğrulanmış formlar.",
+  "showcase_state_title": "Global Durum",
+  "showcase_state_desc_1": "",
+  "showcase_state_desc_2": " ile yönetilen paylaşılan istemci durumu.",
+  "showcase_footer_license": "© {year} {name}. MIT Lisanslı.",
+  "showcase_footer_built": "Son güncelleme tarihi: {date}.",
+  "users_title": "Son Kullanıcılar",
+  "users_desc_1": "",
+  "users_desc_2": " ile verileri çekip önbelleğe alın, ",
+  "users_desc_3": " ile URL'e eşitleyin.",
+  "users_search": "Kullanıcıları ara...",
+  "users_refresh": "Yenile",
+  "users_refreshing": "Yenileniyor...",
+  "users_col_user": "Kullanıcı",
+  "users_col_city": "Şehir",
+  "users_error_status": "İstek {status} durumu ile başarısız oldu.",
+  "users_error_network": "Kullanıcılar yüklenemedi. Lütfen internet bağlantınızı kontrol edin.",
+  "users_empty": "Kullanıcı bulunamadı.",
+  "project_label": "Proje Adı",
+  "project_placeholder": "virastack-app",
+  "project_desc": "Proje adı için 3-50 karakter kullanın.",
+  "project_submit": "Proje Oluştur",
+  "project_submitting": "Oluşturuluyor…",
+  "project_success": "Proje oluşturuldu: {name}",
+  "project_validation_min": "Proje adı en az 3 karakter olmalıdır.",
+  "project_validation_max": "Proje adı en fazla 50 karakter olabilir.",
+  "cart_item_name": "Pamuklu Tişört",
+  "cart_item_variant": "Beyaz / XL",
+  "cart_item_total": "Toplam",
+  "cart_clear": "Temizle"
+}

package/templates-i18n/tanstack/package.json

@@ -0,0 +1,132 @@
+{
+  "name": "virastack",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Premium TanStack Start + React 19 + Tailwind CSS 4 boilerplate focused on clean architecture, UI/UX, and agent-ready developer experience.",
+  "author": {
+    "name": "Ömer Gülçiçek (ViraStack)",
+    "email": "iletisim@omergulcicek.com",
+    "url": "https://omergulcicek.com"
+  },
+  "license": "MIT",
+  "virastack": {
+    "template": "tanstack",
+    "version": "1.0.0",
+    "i18n": true,
+    "url": "https://virastack.com"
+  },
+  "homepage": "https://virastack.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/virastack/start.git"
+  },
+  "bugs": {
+    "url": "https://github.com/virastack/start/issues"
+  },
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "imports": {
+    "#/*": "./src/*"
+  },
+  "scripts": {
+    "dev": "vite dev --port 3000",
+    "build": "vite build",
+    "start": "vite preview --port 3000",
+    "preview": "vite preview --port 3000",
+    "generate-routes": "tsr generate",
+    "clean": "rimraf dist .tanstack .output",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "knip": "knip",
+    "lint": "eslint . --cache",
+    "lint:fix": "eslint . --fix --cache && prettier --write .",
+    "lint:ci": "eslint . --max-warnings=0 && prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "prepare": "husky",
+    "changeset": "changeset",
+    "changeset:version": "changeset version",
+    "changeset:publish": "changeset publish"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx}": [
+      "eslint --fix --cache",
+      "prettier --write"
+    ],
+    "*.{css,md,json}": [
+      "prettier --write"
+    ]
+  },
+  "keywords": [
+    "virastack",
+    "tanstack-start",
+    "tanstack-router",
+    "react-boilerplate",
+    "react",
+    "tanstack",
+    "cursor-rules",
+    "clean-architecture",
+    "typescript",
+    "tanstack-query",
+    "tailwindcss",
+    "base-ui",
+    "dx"
+  ],
+  "dependencies": {
+    "@base-ui/react": "^1.6.0",
+    "@fontsource-variable/inter": "^5.3.0",
+    "@hookform/resolvers": "^5.4.0",
+    "@tailwindcss/vite": "^4.1.18",
+    "@tanstack/react-devtools": "^0.10.9",
+    "@tanstack/react-query": "^5.101.4",
+    "@tanstack/react-query-devtools": "^5.101.4",
+    "@tanstack/react-router": "^1.170.18",
+    "@tanstack/react-router-devtools": "^1.167.0",
+    "@tanstack/react-router-ssr-query": "^1.167.1",
+    "@tanstack/react-start": "^1.168.32",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "framer-motion": "^12.42.2",
+    "lucide-react": "^1.26.0",
+    "nuqs": "^2.9.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-hook-form": "^7.82.0",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.1.18",
+    "usehooks-ts": "^3.1.1",
+    "zod": "^4.4.3",
+    "zustand": "^5.0.14"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.1",
+    "@commitlint/cli": "^21.2.1",
+    "@commitlint/config-conventional": "^21.2.0",
+    "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
+    "@inlang/paraglide-js": "^2.23.0",
+    "@tanstack/eslint-config": "^0.4.0",
+    "@tanstack/router-cli": "^1.167.21",
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "eslint": "^9.20.0",
+    "husky": "^9.1.7",
+    "knip": "^6.29.0",
+    "lint-staged": "^17.2.0",
+    "prettier": "^3.8.1",
+    "prettier-plugin-tailwindcss": "^0.8.1",
+    "rimraf": "^6.1.3",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "lightningcss"
+    ]
+  }
+}