virastack 0.0.1 → 1.0.0

package/src/utils/tools.js

@@ -0,0 +1,48 @@
+/**
+ * Registry of ViraStack tools the CLI knows how to wire up.
+ *
+ * - "dependency" tools are added straight to package.json and installed
+ *   like any other npm package (e.g. @virastack/mask).
+ * - "postinstall-cli" tools ship their own `init` command that writes files
+ *   into the target project (e.g. @virastack/ai writes .cursor/rules), so we
+ *   shell out to them instead of treating them as a runtime dependency.
+ */
+export const TOOLS = [
+  {
+    id: "mask",
+    package: "@virastack/mask",
+    kind: "dependency",
+    version: "latest",
+  },
+  {
+    id: "password",
+    package: "@virastack/password",
+    kind: "dependency",
+    version: "latest",
+  },
+  {
+    id: "ai",
+    package: "@virastack/ai",
+    kind: "postinstall-cli",
+    version: "latest",
+    hiddenFromInit: true,
+  },
+];
+
+export function findTool(id) {
+  return TOOLS.find((tool) => tool.id === id);
+}
+
+/**
+ * Parses a comma-separated tools flag into valid tool ids.
+ * Unknown ids are ignored; empty / missing input yields [].
+ */
+export function parseToolsFlag(value) {
+  if (value == null || value === true) return [];
+
+  return String(value)
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .filter((id) => Boolean(findTool(id)));
+}

package/src/utils/update-package-json.js

@@ -0,0 +1,44 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { findTool } from "./tools.js";
+import { toPackageName } from "./validate-project-name.js";
+import { getCliVersion } from "./package-info.js";
+
+/**
+ * Rewrites the scaffolded package.json: gives it the user's project name
+ * and adds a dependency entry for every selected "dependency"-kind tool
+ * (e.g. @virastack/mask). Tools with an "init" CLI (like @virastack/ai)
+ * are handled separately since they aren't a runtime dependency.
+ */
+export async function updatePackageJson(targetDir, { projectName, tools }) {
+  const pkgPath = path.join(targetDir, "package.json");
+
+  let pkg;
+  try {
+    pkg = JSON.parse(await fs.readFile(pkgPath, "utf8"));
+  } catch {
+    return;
+  }
+
+  pkg.name = toPackageName(projectName);
+  pkg.version = "1.0.0"; // Scaffolded project's own initial version
+  delete pkg.author;
+  delete pkg.repository;
+  delete pkg.bugs;
+  delete pkg.homepage;
+  delete pkg.keywords;
+
+  if (pkg.virastack) {
+    pkg.virastack.version = getCliVersion();
+  }
+
+  pkg.dependencies = pkg.dependencies ?? {};
+  for (const toolId of tools) {
+    const tool = findTool(toolId);
+    if (tool?.kind === "dependency") {
+      pkg.dependencies[tool.package] = tool.version ?? "^1.0.0";
+    }
+  }
+
+  await fs.writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+}

package/src/utils/update-readme.js

@@ -0,0 +1,25 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+/**
+ * Personalizes the scaffolded README: renames the H1 to the user's project
+ * and strips the marketing hero image (assets/ is not copied into projects).
+ */
+export async function updateReadme(targetDir, projectName) {
+  const readmePath = path.join(targetDir, "README.md");
+
+  let content;
+  try {
+    content = await fs.readFile(readmePath, "utf8");
+  } catch {
+    return;
+  }
+
+  let updated = content
+    .replace(/^#\s+.+$/m, `# ${projectName}`)
+    .replace(/^!\[.*?\]\(\.\/assets\/.*?\)\n*/m, "");
+
+  if (updated === content) return;
+
+  await fs.writeFile(readmePath, updated);
+}

package/src/utils/validate-project-name.js

@@ -0,0 +1,26 @@
+// Same shape npm itself enforces for package names (scoped names included).
+const NPM_NAME_PATTERN = /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+
+/**
+ * Returns null when valid, or an error code ("empty" | "invalid") otherwise.
+ * "." is always valid — it means "use the current directory".
+ */
+export function validateProjectName(value) {
+  const trimmed = (value ?? "").trim();
+
+  if (trimmed.length === 0) return "empty";
+  if (trimmed === ".") return null;
+  if (!NPM_NAME_PATTERN.test(trimmed)) return "invalid";
+
+  return null;
+}
+
+export function toPackageName(name) {
+  const sanitized = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-~]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  return sanitized.length > 0 ? sanitized : "virastack-app";
+}

package/templates/nextjs/.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/nextjs/.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/nextjs/.env.example

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

package/templates/nextjs/.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/nextjs/.husky/commit-msg

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

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

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

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

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

package/templates/nextjs/.prettierignore

@@ -0,0 +1,6 @@
+.next
+node_modules
+pnpm-lock.yaml
+public
+CHANGELOG.md
+.changeset

package/templates/nextjs/.prettierrc

@@ -0,0 +1,42 @@
+{
+  "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$",
+    "^next($|/)",
+    "",
+    "^@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/nextjs/.vscode/extensions.json

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

package/templates/nextjs/.vscode/settings.json

@@ -0,0 +1,20 @@
+{
+  "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,
+    "**/build": true,
+    "**/dist": true,
+    "**/node_modules": true
+  }
+}

package/templates/nextjs/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/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/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.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);