virastack 0.0.1 → 1.0.0

package/templates/nextjs/src/styles/tailwind.css

@@ -0,0 +1,122 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+
+@custom-variant dark (&:is(.dark *));
+
+:root {
+  --radius: 0.65rem;
+
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+
+  --destructive: oklch(0.577 0.245 27.325);
+  --destructive-foreground: oklch(0.985 0 0);
+
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+
+  --destructive: oklch(0.704 0.191 22.216);
+  --destructive-foreground: oklch(0.985 0 0);
+
+  --border: oklch(1 0 0 / 12%);
+  --input: oklch(1 0 0 / 18%);
+  --ring: oklch(0.556 0 0);
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+
+  --font-sans: var(--font-inter);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+
+  html {
+    @apply scroll-smooth;
+  }
+
+  body {
+    @apply bg-background text-foreground;
+  }
+
+  button:not(:disabled),
+  [role="button"]:not(:disabled) {
+    cursor: pointer;
+  }
+}

package/templates/nextjs/src/types/site-config.types.ts

@@ -0,0 +1,10 @@
+export type SiteConfig = {
+  name: string;
+  description: string;
+  url: string;
+  ogImage: string;
+  links: {
+    github: string;
+    twitter: string;
+  };
+};

package/templates/nextjs/tsconfig.json

@@ -0,0 +1,45 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"],
+      "@/ui": ["./src/components/ui/index.ts"],
+      "@/ui/*": ["./src/components/ui/*"],
+      "@/layout": ["./src/components/layout/index.ts"],
+      "@/layout/*": ["./src/components/layout/*"],
+      "@/hooks": ["./src/hooks/index.ts"],
+      "@/hooks/*": ["./src/hooks/*"],
+      "@/data": ["./src/data/index.ts"],
+      "@/data/*": ["./src/data/*"],
+      "@/schemas": ["./src/schemas/index.ts"],
+      "@/schemas/*": ["./src/schemas/*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}

package/templates/tanstack/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets).
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).

package/templates/tanstack/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/templates/tanstack/.env.example

@@ -0,0 +1,6 @@
+# Public (exposed to the browser) — must be prefixed with VITE_
+VITE_APP_URL="http://localhost:3000"
+VITE_APP_NAME="ViraStack Start - TanStack Edition"
+
+# Server-only (never exposed to the browser)
+# NODE_ENV is set automatically by Vite — no need to define it here.

package/templates/tanstack/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm run typecheck
+
+      - name: Lint
+        run: pnpm run lint:ci
+
+      - name: Knip
+        run: pnpm run knip
+
+      - name: Build
+        run: pnpm run build

package/templates/tanstack/.husky/commit-msg

@@ -0,0 +1 @@
+npx --no -- commitlint --edit "$1"

package/templates/tanstack/.husky/pre-commit

@@ -0,0 +1 @@
+npx --no -- lint-staged

package/templates/tanstack/.husky/pre-push

@@ -0,0 +1 @@
+npm run typecheck && npm run lint:ci

package/templates/tanstack/.prettierignore

@@ -0,0 +1,7 @@
+.next
+node_modules
+pnpm-lock.yaml
+public
+CHANGELOG.md
+.changeset
+src/routeTree.gen.ts

package/templates/tanstack/.prettierrc

@@ -0,0 +1,41 @@
+{
+  "singleQuote": false,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "plugins": ["@ianvs/prettier-plugin-sort-imports", "prettier-plugin-tailwindcss"],
+  "tailwindFunctions": ["cn", "clsx", "cva"],
+  "tailwindStylesheet": "./src/styles/tailwind.css",
+  "importOrder": [
+    "^react$",
+    "^@tanstack/.*",
+    "",
+    "^zustand($|/)",
+    "^lucide-react($|/)",
+    "<THIRD_PARTY_MODULES>",
+    "",
+    "^@/types($|/)",
+    "^@/constants($|/)",
+    "^@/schemas($|/)",
+    "^@/config($|/)",
+    "^@/env($|/)",
+    "",
+    "^@/assets($|/)",
+    "^@/styles($|/)",
+    "^@/lib($|/)",
+    "^@/helpers($|/)",
+    "",
+    "^@/providers($|/)",
+    "^@/stores($|/)",
+    "^@/hooks($|/)",
+    "^@/data($|/)",
+    "",
+    "^@/components($|/)",
+    "^@/layout($|/)",
+    "^@/features($|/)",
+    "^@/ui($|/)",
+    "^@/.*",
+    "",
+    "^[./]"
+  ],
+  "importOrderParserPlugins": ["typescript", "jsx"]
+}

package/templates/tanstack/.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "esbenp.prettier-vscode",
+    "dbaeumer.vscode-eslint",
+    "bradlc.vscode-tailwindcss"
+  ]
+}

package/templates/tanstack/.vscode/settings.json

@@ -0,0 +1,22 @@
+{
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "files.exclude": {
+    "**/.git": true,
+    "**/.svn": true,
+    "**/.hg": true,
+    "**/.DS_Store": true,
+    "**/Thumbs.db": true,
+    "**/.cache": true,
+    "**/.next": true,
+    "**/.tanstack": true,
+    "**/.output": true,
+    "**/build": true,
+    "**/dist": true,
+    "**/node_modules": true
+  }
+}

package/templates/tanstack/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Ömer Gülçiçek (ViraStack)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/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/tanstack/commitlint.config.js

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

package/templates/tanstack/eslint.config.js

@@ -0,0 +1,28 @@
+//  @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",
+      "dist/**",
+      ".tanstack/**",
+      ".output/**",
+    ],
+  },
+];

package/templates/tanstack/knip.config.js

@@ -0,0 +1,22 @@
+/** @type {import('knip').KnipConfig} */
+const config = {
+  entry: ["src/router.tsx", "src/start.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",
+  ],
+  ignoreDependencies: ["tailwindcss", "tw-animate-css"],
+  rules: {
+    dependencies: "error",
+    exports: "warn",
+    types: "warn",
+    files: "warn",
+  },
+};
+
+module.exports = config;