virastack 0.0.1 → 1.0.1

package/templates/nextjs/README.md

@@ -0,0 +1,202 @@
+<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 — Next.js Edition
+
+_The Next.js boilerplate that feels effortless._
+
+[![ViraStack Next.js](https://img.shields.io/badge/ViraStack-Next.js-%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/nextjs-boilerplate/)
+
+**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 Next.js 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**
+
+- ⚡ **Next.js 16** — App Router, Turbopack, React Compiler
+- ⚛️ **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                                                   |
+| :--------------------- | :----- | :------------------------------------------------------------ |
+| `NEXT_PUBLIC_APP_URL`  | Public | Canonical app URL (default `http://localhost:3000`)           |
+| `NEXT_PUBLIC_APP_NAME` | Public | Product name shown in UI/metadata (default `ViraStack Start`) |
+
+`NODE_ENV` is set by Next.js — do not define it manually. Add new vars in both `.env.example` and `src/env.ts`.
+
+## Scripts
+
+| Script                          | Description                                  |
+| :------------------------------ | :------------------------------------------- |
+| `dev`                           | Start the dev server (Turbopack)             |
+| `build`                         | Production build                             |
+| `start`                         | Serve the production build                   |
+| `analyze`                       | Build with bundle analyzer                   |
+| `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/
+├── app/                  # Routes, layouts, metadata (App Router only)
+├── 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/
+└── 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/app/page.tsx` with your own page
+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         |
+| `next.config.ts`              | Remote image domains and Next.js options |
+| `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
+
+Optimized for [Vercel](https://vercel.com/):
+
+1. Push the repo and import the project in Vercel (or your host of choice)
+2. Set `NEXT_PUBLIC_APP_URL` and `NEXT_PUBLIC_APP_NAME` from `.env.example`
+3. Run `pnpm analyze` locally before shipping if bundle size matters
+4. Deploy — `pnpm build` / `pnpm start` work the same on any Node host
+
+## 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/nextjs/_gitignore

@@ -0,0 +1,45 @@
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files
+.env*
+!.env.example
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# cache / tooling
+.eslintcache
+.knip
+.turbo

package/templates/nextjs/commitlint.config.js

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

package/templates/nextjs/eslint.config.mjs

@@ -0,0 +1,27 @@
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+import { defineConfig, globalIgnores } from "eslint/config";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  {
+    rules: {
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
+      ],
+      "no-console": ["warn", { allow: ["warn", "error"] }],
+    },
+  },
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

package/templates/nextjs/knip.config.js

@@ -0,0 +1,25 @@
+/** @type {import('knip').KnipConfig} */
+const config = {
+  entry: [
+    "src/app/**/{page,layout,template,default,loading,not-found,error,global-error}.{ts,tsx}",
+    "src/app/**/{sitemap,robots,manifest}.{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;

package/templates/nextjs/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/templates/nextjs/next.config.ts

@@ -0,0 +1,39 @@
+import path from "node:path";
+import type { NextConfig } from "next";
+
+import createBundleAnalyzer from "@next/bundle-analyzer";
+
+const withBundleAnalyzer = createBundleAnalyzer({
+  enabled: process.env.ANALYZE === "true",
+});
+
+const nextConfig: NextConfig = {
+  reactCompiler: true,
+  turbopack: {
+    root: path.join(import.meta.dirname),
+  },
+  images: {
+    remotePatterns: [
+      // FIXME: add your own remote image domains here, e.g.:
+      // { protocol: "https", hostname: "images.unsplash.com" },
+    ],
+  },
+  async headers() {
+    return [
+      {
+        source: "/:path*",
+        headers: [
+          { key: "X-Frame-Options", value: "DENY" },
+          { key: "X-Content-Type-Options", value: "nosniff" },
+          { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
+          {
+            key: "Permissions-Policy",
+            value: "camera=(), microphone=(), geolocation=()",
+          },
+        ],
+      },
+    ];
+  },
+};
+
+export default withBundleAnalyzer(nextConfig);

package/templates/nextjs/package.json

@@ -0,0 +1,115 @@
+{
+  "name": "virastack",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Premium Next.js 16 + 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": "nextjs",
+    "version": "1.0.0",
+    "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"
+  },
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "analyze": "cross-env ANALYZE=true next build",
+    "clean": "rimraf .next",
+    "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",
+    "nextjs-boilerplate",
+    "nextjs-starter",
+    "react-boilerplate",
+    "react",
+    "nextjs",
+    "cursor-rules",
+    "clean-architecture",
+    "typescript",
+    "tanstack-query",
+    "tailwindcss",
+    "base-ui",
+    "dx"
+  ],
+  "dependencies": {
+    "@base-ui/react": "^1.6.0",
+    "@hookform/resolvers": "^5.4.0",
+    "@next/bundle-analyzer": "^16.2.11",
+    "@tanstack/react-query": "^5.101.4",
+    "@tanstack/react-query-devtools": "^5.101.4",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "framer-motion": "^12.42.2",
+    "lucide-react": "^1.25.0",
+    "next": "16.2.11",
+    "next-themes": "^0.4.6",
+    "nuqs": "^2.9.1",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "react-hook-form": "^7.82.0",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.6.0",
+    "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",
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "babel-plugin-react-compiler": "1.0.0",
+    "cross-env": "^10.1.0",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.11",
+    "husky": "^9.1.7",
+    "knip": "^6.28.0",
+    "lint-staged": "^17.1.1",
+    "prettier": "^3.9.6",
+    "prettier-plugin-tailwindcss": "^0.8.1",
+    "rimraf": "^6.1.3",
+    "tailwindcss": "^4",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5"
+  }
+}