🌊 Starkon - Next.js Starter Generator

🚀 Create production-ready Next.js applications in seconds, not hours

Starkon is an opinionated Next.js starter generator. It scaffolds complete applications through an interactive CLI and ships multiple production-ready starting points for SaaS, corporate, landing page, dashboard, and minimal setups.

What Starkon Is

• A CLI-first project generator for bootstrapping full Next.js applications
• A curated set of starter templates with shared conventions and ready-to-run app structure
• A faster alternative to assembling auth, i18n, UI primitives, and project structure by hand

What Starkon Is Not

• Not a general-purpose UI component library to install as a runtime dependency in an existing app
• Not a lightweight single-component package similar to a design system primitive export
• Not a drop-in replacement for an already-established application architecture

The reusable components inside this repository exist to power the generated starter projects. The main product is the scaffolding workflow invoked by npx starkon.

✨ Interactive Template Selection

npx starkon my-app

The interactive menu shows 3 primary templates. You can access 3 additional specialized templates via the --template flag:

• 🏗️ Full App Starter - Full-stack with auth & i18n
• 🎯 Landing Page - Marketing-optimized single page
• 🏢 Corporate - Business website with CMS
• 📊 Dashboard - Admin panel optimized (manual: --template dashboard)
• ⚡ Basic - Essential setup (manual: --template basic)
• 🎯 Minimal - Bare-bones (manual: --template minimal)

⚡ Quick Start

🎯 Interactive CLI Menu

Simply run the command and choose your template:

npx starkon my-app

You'll see an interactive menu with 3 primary options:

• ❯ Full App Starter - Full-featured with auth & i18n
• Landing Starter - Single-page marketing site
• Corporate Starter - Business website with CMS

Use ↑↓ arrow keys to navigate and Enter to select.

🚀 Complete Setup

npx starkon my-awesome-app
# ↓ Interactive menu appears
# ↓ Select template with arrow keys
# ↓ Press Enter to confirm
cd my-awesome-app
npm install
npm run dev

Your Next.js app will be running at http://localhost:3000 🎉

🏃‍♂️ Skip Interactive Menu

Use --template when you want direct access to all 6 available templates without going through the interactive selector.

You can also specify template directly:

npx starkon my-app --template corporate  # Business website
npx starkon my-app --template landing    # Marketing page
npx starkon my-app --template standard   # Full-stack app

🎯 Template Library

Choose the perfect starting point for your specific use case:

🏢 Corporate Template ⭐

Complete business website with content management system.

npx starkon company-website --template corporate

Perfect for:

• Corporate websites
• Agency portfolios
• Business landing pages
• Service companies

Includes:

• 📄 Pages: Home, About, Services, Blog, Gallery, Contact
• 🧩 Components: ServiceCard, TeamMember, BlogCard, GalleryItem
• 📝 Content System: Built-in content management with TypeScript interfaces
• 🎨 Professional Design: Clean, modern business aesthetic
• 📱 Responsive: Mobile-optimized layouts

Excludes: Authentication system, i18n complexity for cleaner corporate focus

🎯 Landing Template ⭐ Popular

Single-page marketing websites optimized for conversions.

npx starkon product-launch --template landing

Perfect for:

• Product launches
• SaaS marketing sites
• Portfolio websites
• Event pages

Includes:

• 🎨 Sections: Hero, Features, Testimonials, CTA, Contact
• ⚡ Animations: Smooth scroll-triggered animations with Framer Motion
• 📝 Forms: Contact forms with validation
• 🎯 CTA Optimized: Conversion-focused design patterns

Excludes: Authentication, i18n, dashboard components for faster loading

🏗️ Full App Starter (Full-Featured)

Complete full-stack setup with all enterprise features.

npx starkon enterprise-app --template standard

Perfect for:

• SaaS applications
• Admin dashboards
• Enterprise tools
• Multi-user platforms

Includes:

• 🔐 Authentication: JWT-based auth with session management
• 🌍 i18n: English/Turkish with easy language addition
• 📊 Dashboard: Admin panels and user management
• 🛡️ Security: Protected routes, XSS protection
• 🎨 Complete UI Kit: 46 production-ready components

⚡ Basic Template

Essential Next.js setup without complexity.

npx starkon simple-app --template basic

Perfect for:

• Small projects
• Prototypes
• Learning Next.js
• Quick experiments

Includes: Next.js 16, TypeScript, Tailwind CSS, ESLint Excludes: Authentication, i18n, complex UI components

📊 Dashboard Template

Admin dashboard optimized for data-heavy applications.

npx starkon admin-panel --template dashboard

Perfect for:

• Admin dashboards
• Analytics tools
• Data management
• Internal tools

Includes: Dashboard layout, data tables, charts integration, auth system Excludes: Public marketing pages

🎯 Minimal Template

Bare-bones Next.js setup for maximum control.

npx starkon minimal-app --template minimal

Perfect for:

• Custom implementations
• Learning projects
• Starting from scratch

Includes: Next.js 16, TypeScript only Excludes: Everything else - build your own way

🏗️ Generated Project Overview

Project Structure

generated-app/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (auth)/            # 🔐 Protected route group
│   │   ├── (authentication)/  # 🔑 Auth flows (Login, register, etc.)
│   │   ├── corporate/         # 🏢 Corporate pages
│   │   ├── public/            # 🎯 Marketing pages
│   │   ├── page.tsx           # Entry point
│   │   └── layout.tsx         # Root layout
│   ├── features/              # 🏗️ Feature-Sliced modules
│   │   └── auth/              # Complete Auth feature
│   │       ├── context/       # AuthProvider
│   │       ├── hooks/         # useAuth
│   │       ├── services/      # API communication
│   │       ├── types/         # Auth definitions
│   │       └── lib/           # Feature utilities
│   ├── components/            # Shared UI components
│   │   ├── core/              # 🧩 Base UI Kit primitives
│   │   ├── forms/             # Form abstractions
│   │   └── layout/            # Navigation & Footer
│   ├── lib/                   # 🛡️ Enterprise utilities
│   │   ├── api.ts             # Monitored Axios client
│   │   ├── auth-middleware.ts # Edge-compatible security
│   │   ├── monitoring/        # Client-side telemetry
│   │   └── i18n/              # Transport error handling
│   ├── constant/              # ⚙️ Global configurations
│   ├── i18n/                  # i18next initialization
│   ├── messages/              # 🌍 Consolidated translations
│   ├── hooks/                 # Shared React hooks
│   ├── providers/             # Global Context providers
│   ├── store/                 # Client state (Zustand)
│   ├── styles/                # Global CSS (HSL system)
│   └── types/                 # Shared TypeScript types
├── public/                    # Static assets
├── tailwind.config.mjs        # Premium HSL design system
└── next.config.mjs            # Next.js configuration

Technology Stack In The Generated App

Core Framework:

• Next.js 16 - App Router, Server Components, optimized performance
• React 19 - Latest React features and improvements
• TypeScript 5.7 - Full type safety and developer experience

UI & Design:

• Premium HSL Design System - Dynamic tokens for void-black, obsidian, and arcly-blue
• Radix UI - Accessible, unstyled component primitives
• Tailwind CSS 3.4 - Utility-first styling with custom glassmorphism effects
• class-variance-authority - Type-safe component variants
• Framer Motion - Smooth animations and transitions
• Lucide React - Beautiful, consistent icon library
• Advanced CSS Variables - System-wide theming with semantic tokens

State & Data:

• React Query (@tanstack/react-query) - Server state management and caching
• Zustand 5.0 - Lightweight client state management
• Redux + Redux Persist - Optional complex state with persistence
• React Hook Form - Performant forms with validation

API & HTTP:

• Monitored Axios Client - HTTP client with TTFB and duration telemetry
• Edge-Compatible Auth - Web Crypto based JWT verification
• Request/response queuing - Token refresh handling
• FormData support - File upload integration
• Advanced Interceptors - Auto token attachment and telemetry collection

Forms & Validation:

• React Hook Form - Form state management
• Zod - TypeScript-first schema validation
• @hookform/resolvers - Form validation integration

Internationalization:

• i18next - Complete i18n solution
• react-i18next - React integration
• Browser language detection - Automatic locale detection
• localStorage + cookie persistence - Language preference storage

Advanced Features:

• cmdk - Command menu (Cmd+K)
• react-dropzone - File upload interface
• @tanstack/react-table - Headless table library
• date-fns - Date manipulation utilities
• crypto-js - Encryption utilities
• react-error-boundary - Error handling

Development:

• ESLint - Code linting with Next.js rules
• Prettier - Code formatting with Tailwind plugin
• Jest - Unit testing framework
• React Testing Library - Component testing utilities
• Husky - Git hooks
• Commitizen - Conventional commits

🔐 Authentication System

Features

• JWT Tokens - Secure access and refresh token system
• Auto-refresh - Automatic token renewal with 5-minute buffer
• Session Management - Persistent login with "Remember Me"
• Protected Routes - Middleware-based route protection
• Mock Development - Built-in test users for development
• 4 Auth Flows - Login, Register, Forgot Password, Reset Password, Verify Email

Development Users

// Available test accounts
admin@example.com    / admin123     // Full admin access
user@example.com     / user123      // Standard user
demo@example.com     / demo123      // Demo account

Auth Usage

import { useAuth } from '@/hooks/useAuth'

function Dashboard() {
  const { user, logout, isAuthenticated } = useAuth()

  if (!isAuthenticated) return <LoginForm />

  return <h1>Welcome {user.name}!</h1>
}

Authentication Architecture

5-Layer System:

1. Token Management (features/auth/services/sessionTokenManager.ts) - sessionStorage with 5-minute refresh buffer
2. API Service (features/auth/services/authApiService.ts) - Environment-based mock/real API switching
3. Auth Provider (features/auth/context/AuthProvider.tsx) - React Context with periodic validation
4. Middleware (lib/auth-middleware.ts) - Edge-compatible security routing
5. Axios Interceptors (lib/api.ts) - Auto token attachment and telemetry collection

🌍 Internationalization

Built-in Language Support

• English (en) - Complete translations
• Turkish (tr) - Native language support
• Browser Detection - Automatic language detection
• URL Persistence - Language state in URL parameters (?lang=en)
• localStorage & Cookie - Persistent language preference

Detection Priority

1. localStorage - Key: language (permanent)
2. Cookie - Key: language (365-day expiry)
3. URL Parameter - ?lang=tr
4. Browser Navigator - navigator.language
5. Default - Turkish (tr)

Adding New Languages

# 1. Create translation file
src/locales/es/translation.json

# 2. Add to supported locales
src/lib/i18n.ts

i18n Usage

import { useTranslation } from 'react-i18next'

function Component() {
  const { t, i18n } = useTranslation()

  // Change language
  i18n.changeLanguage('en')

  return <h1>{t('welcome.title')}</h1>
}

🎨 UI Component System

Core Components (46)

Basic Components:

// Form Components
<Button variant="default | outline | ghost | destructive | link" size="sm | md | lg | icon" />
<Input type="text | email | password" />
<PasswordInput showStrength={true} />
<NumberInput min={0} max={100} />
<Textarea placeholder="Enter text..." />
<Checkbox checked={true} />
<Switch enabled={true} />
<Select options={options} />

Layout Components:

<Card>
  <CardHeader>
    <CardTitle>Title</CardTitle>
  </CardHeader>
  <CardContent>Content</CardContent>
</Card>
<Separator orientation="horizontal | vertical" />
<Accordion type="single | multiple" />
<Tabs defaultValue="tab1">
  <TabsList>
    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
  </TabsList>
</Tabs>
<Collapsible>
  <CollapsibleTrigger>Toggle</CollapsibleTrigger>
  <CollapsibleContent>Hidden content</CollapsibleContent>
</Collapsible>

Data Display:

// Tables with @tanstack/react-table
<DataTable data={data} columns={columns} />
<EnhancedDataTable data={data} columns={columns} searchable sortable />
<DataGrid data={data} />
<Table>
  <TableHeader>
    <TableRow>
      <TableHead>Column</TableHead>
    </TableRow>
  </TableHeader>
</Table>
<Badge variant="default | secondary | outline | destructive" />
<Avatar src="/avatar.jpg" fallback="JD" />

Date & Time:

<Calendar selected={date} onSelect={setDate} />
<DatePicker value={date} onChange={setDate} />
<MonthYearPicker value={date} onChange={setDate} />
<ModernDatePicker value={date} onChange={setDate} />

Navigation:

<CommandMenu>
  <CommandInput placeholder="Search..." />
  <CommandList>
    <CommandGroup heading="Suggestions">
      <CommandItem>Calendar</CommandItem>
    </CommandGroup>
  </CommandList>
</CommandMenu>
<DynamicBreadcrumb items={items} />
<EnhancedPaginationControls page={1} totalPages={10} />
<Stepper steps={steps} currentStep={0} />
<ModernDrawer open={isOpen} onClose={close}>
  <DrawerContent>Content</DrawerContent>
</ModernDrawer>

Feedback:

<Alert variant="default | destructive | warning | info">
  <AlertTitle>Alert Title</AlertTitle>
  <AlertDescription>Description</AlertDescription>
</Alert>
<AlertDialog>
  <AlertDialogTrigger>Open</AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogTitle>Are you sure?</AlertDialogTitle>
  </AlertDialogContent>
</AlertDialog>
<Skeleton className="w-full h-20" />
<LoadingSpinner size="sm | md | lg" />
<Progress value={50} />
<Toast title="Success" description="Action completed" />

Advanced Components:

<Dialog open={isOpen} onOpenChange={setIsOpen}>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Dialog Title</DialogTitle>
    </DialogHeader>
  </DialogContent>
</Dialog>
<Dropdown>
  <DropdownTrigger>Menu</DropdownTrigger>
  <DropdownContent>
    <DropdownItem>Item 1</DropdownItem>
  </DropdownContent>
</Dropdown>
<Popover>
  <PopoverTrigger>Open</PopoverTrigger>
  <PopoverContent>Content</PopoverContent>
</Popover>
<Tooltip content="Tooltip text">
  <button>Hover me</button>
</Tooltip>
<ScrollArea className="h-96">
  <div>Scrollable content</div>
</ScrollArea>
<Slider value={[50]} onValueChange={setValue} />

Enterprise Components:

// File Upload with react-dropzone
<FileUpload
  accept={{ 'image/*': ['.png', '.jpg'] }}
  maxSize={5242880}
  onDrop={handleDrop}
/>

// Rich Text Editor
<RichTextEditor
  value={content}
  onChange={setContent}
  placeholder="Start typing..."
/>

// Advanced Search with Filters
<EnhancedSearchFilters
  filters={filters}
  onFilterChange={handleFilterChange}
/>

// Accessibility Enhancer
<AccessibilityEnhancer skipToContentId="main">
  <YourContent />
</AccessibilityEnhancer>

// Enterprise Error Boundary
<EnterpriseErrorBoundary
  fallback={<ErrorFallback />}
  onError={logError}
>
  <YourApp />
</EnterpriseErrorBoundary>

Corporate Components

// Service showcase
<ServiceCard
  title="Web Development"
  description="Custom web solutions"
  features={["React", "Next.js", "TypeScript"]}
  icon={Code}
  href="/services/web"
/>

// Team member display
<TeamMember
  name="John Doe"
  role="Lead Developer"
  bio="10+ years experience"
  image="/team/john.jpg"
  social={{ linkedin: "...", github: "..." }}
  skills={["React", "Node.js", "AWS"]}
/>

// Blog post cards
<BlogCard
  title="Getting Started with Next.js"
  excerpt="Learn the fundamentals..."
  author={{ name: "Jane Smith", avatar: "/authors/jane.jpg" }}
  category="Tutorial"
  readingTime="5 min read"
  publishedAt="2024-01-15"
/>

// Gallery items
<GalleryItem
  image="/projects/project1.jpg"
  title="Project Name"
  category="Web Design"
  description="Project description"
/>

Landing Page Sections

// Hero section with CTA
<Hero
  title="Build Amazing Apps"
  subtitle="Next.js starter for rapid development"
  primaryAction="Get Started"
  secondaryAction="View Demo"
/>

// Feature showcase
<Features
  title="Everything You Need"
  features={[
    { title: "Fast Setup", icon: Zap, description: "..." },
    { title: "TypeScript", icon: Shield, description: "..." }
  ]}
/>

// Social proof
<Testimonials
  title="What Developers Say"
  testimonials={[
    { name: "Developer", role: "CTO", content: "Amazing tool!" }
  ]}
/>

// Call to action
<CTA
  title="Ready to Build?"
  description="Start your next project today"
  primaryAction="Get Started"
  secondaryAction="View Pricing"
/>

🪝 Custom Hooks

Authentication

import { useAuth } from '@/hooks/useAuth'

const { user, login, logout, isAuthenticated, loading } = useAuth()

Theme Management

import { useTheme } from '@/hooks/useTheme'

const { theme, setTheme, systemTheme } = useTheme()
setTheme('dark' | 'light' | 'system')

Toast Notifications

import { useToast } from '@/hooks/useToast'

const { toast } = useToast()
toast.success('Success message')
toast.error('Error message')
toast.warning('Warning message')
toast.info('Info message')
toast.promise(asyncFn, {
  loading: 'Loading...',
  success: 'Done!',
  error: 'Failed',
})

Locale Management

import { useLocale } from '@/hooks/useLocale'

const { locale, setLocale, availableLocales } = useLocale()
setLocale('en' | 'tr')

Clipboard Utilities

import { useClipboard } from '@/hooks/useClipboard'

const { copy, copied, error } = useClipboard()
copy('Text to copy')

Password Strength

import { usePasswordStrength } from '@/hooks/usePasswordStrength'

const { strength, score, feedback } = usePasswordStrength(password)
// Returns: weak | fair | good | strong

Form Utilities

import { useForm } from '@/hooks/useForm'

const { values, errors, handleChange, handleSubmit } = useForm({
  initialValues: { email: '', password: '' },
  onSubmit: async (values) => {
    /* ... */
  },
})

🔌 Providers

Auth Provider

Manages authentication state across the application.

// Wrap your app
import { AuthProvider } from '@/providers/AuthProvider'
;<AuthProvider>
  <YourApp />
</AuthProvider>

// Access auth state
const { user, isAuthenticated, login, logout } = useAuth()

i18n Provider

Provides internationalization support.

import { I18nProvider } from '@/providers/I18nProvider'
;<I18nProvider>
  <YourApp />
</I18nProvider>

React Query Provider

Configures React Query for data fetching and caching.

import { ReactQueryProvider } from '@/providers/ReactQueryProvider'
;<ReactQueryProvider>
  <YourApp />
</ReactQueryProvider>

Theme Provider

Manages dark/light theme with system preference detection.

import { ThemeProvider } from '@/providers/theme-provider'
;<ThemeProvider defaultTheme='system' storageKey='theme'>
  <YourApp />
</ThemeProvider>

Toast Provider

Displays toast notifications throughout the app.

import { ToastProvider } from '@/providers/toast-provider'
;<ToastProvider>
  <YourApp />
</ToastProvider>

🛠️ Development Workflow

Getting Started

# 1. Create project with interactive menu
npx starkon my-project
# ↓ Choose template from menu

# 2. Setup development
cd my-project
npm install

# 3. Start development server
npm run dev

# 4. Open browser
open http://localhost:3000

Code Quality

# Linting and formatting
npm run lint              # ESLint check
npm run lint:fix          # Auto-fix ESLint errors
npm run prettier          # Format code
npm run prettier:check    # Check formatting

# Type checking
npm run type-check        # TypeScript validation

# Testing
npm test                  # Run test suite
npm run test:watch        # Watch mode testing
npm run test:coverage     # Coverage report

Build and Deploy

# Production build
npm run build

# Analyze bundle size
npm run analyze           # Opens webpack-bundle-analyzer

# Start production server
npm run start

🌟 CLI Reference

Basic Usage

# Interactive template selection (3 main templates)
npx starkon <project-name>

# Or specify any of 6 templates directly
npx starkon <project-name> --template <template-type>

Options

Template Types

Interactive Menu (3 templates):

Manual Selection Only (3 templates):

Advanced Examples

# Interactive template selection (recommended)
npx starkon my-awesome-project

# Skip interactive menu with specific template
npx starkon acme-corp --template corporate --skip-git

# Landing page with verbose output
npx starkon product-launch --template landing --verbose

# Configuration management
npx starkon --config-set locale=en
npx starkon --config-get locale
npx starkon --clear-cache

📊 Feature Comparison

🚀 Deployment Guide

🟢 Vercel (Recommended)

Zero-configuration deployment for Next.js apps:

# Install Vercel CLI
npm install -g vercel

# Deploy
vercel

# Production deployment
vercel --prod

Features:

• Automatic builds on git push
• Edge functions support
• Built-in analytics
• Custom domains

🟠 Netlify

Great for static and hybrid apps:

# Build for deployment
npm run build

# Deploy to Netlify
netlify deploy --prod --dir=.next

🔵 Docker

For containerized deployment, add a Dockerfile to your scaffolded project:

# Example Dockerfile (add to your project after scaffolding)
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

# Build and run
docker build -t my-starkon-app .
docker run -p 3000:3000 my-starkon-app

Note: Dockerfile is not included in the Starkon CLI package itself. Add it to your scaffolded project as needed.

☁️ Other Platforms

• Railway: railway deploy
• Render: Connect GitHub repository
• AWS Amplify: Push to connected git branch
• Google Cloud: gcloud app deploy

⚙️ Configuration

Environment Variables

Create .env.local in your project root:

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:3001/api
NODE_ENV=development

# Authentication (Standard & Dashboard templates)
NEXTAUTH_SECRET=your-secret-key-here-change-in-production
NEXTAUTH_URL=http://localhost:3000

# Database (if using)
DATABASE_URL=postgresql://user:pass@localhost:5432/db

# Analytics (optional)
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

# App Configuration
NEXT_PUBLIC_APP_NAME=My Starkon App
NEXT_PUBLIC_APP_URL=http://localhost:3000

User Configuration

CLI configuration stored in ~/.starkon/config.json:

{
  "defaultTemplate": "corporate",
  "preferredPackageManager": "pnpm",
  "locale": "en",
  "skipGit": false,
  "skipUpdateCheck": false,
  "telemetryEnabled": true
}

By default, Starkon detects your system locale and falls back to English when it cannot determine a supported language.

🧪 Testing

Running Tests

npm test                  # Run all tests
npm run test:watch        # Watch mode
npm run test:coverage     # Coverage report

Writing Tests

import { render, screen } from '@testing-library/react'
import { Button } from '@/components/core/button'

test('Button renders correctly', () => {
  render(<Button>Click me</Button>)
  expect(screen.getByRole('button')).toHaveTextContent('Click me')
})

🎨 Customization

Theme System

Customize your brand colors in tailwind.config.mjs:

// tailwind.config.mjs
export default {
  theme: {
    extend: {
      colors: {
        primary: {
          50: 'hsl(210 40% 98%)',
          100: 'hsl(210 40% 96%)',
          // ... your brand colors
        },
      },
      animation: {
        'fade-in': 'fadeIn 0.5s ease-in-out',
        'slide-in': 'slideIn 0.3s ease-out',
        // ... custom animations
      },
    },
  },
}

Component Variants

Using class-variance-authority for type-safe variants:

// Custom component with variants
import { cva } from 'class-variance-authority'
import { cn } from '@/lib/utils'

const buttonVariants = cva('base-styles', {
  variants: {
    variant: {
      default: 'bg-primary text-white',
      outline: 'border border-primary text-primary',
      ghost: 'hover:bg-accent',
    },
    size: {
      sm: 'px-3 py-1.5 text-sm',
      lg: 'px-6 py-3 text-lg',
    },
  },
  defaultVariants: {
    variant: 'default',
    size: 'default',
  },
})

export function CustomButton({ variant, size, className, ...props }) {
  return <button className={cn(buttonVariants({ variant, size }), className)} {...props} />
}

Dark Mode

Theme switching with system preference detection:

import { useTheme } from '@/hooks/useTheme'

function ThemeToggle() {
  const { theme, setTheme } = useTheme()

  return <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>Toggle Theme</button>
}

📋 Available Scripts

Development

npm run dev              # Next.js development server (Turbo mode)
npm run build            # Production build
npm run start            # Production server
npm run analyze          # Bundle analyzer (set ANALYZE=true)

Code Quality

npm run lint             # ESLint check
npm run type-check       # TypeScript validation
npm run prettier         # Code formatting
npm run prettier:check   # Check formatting only

Testing

npm test                 # Jest test runner
npm run test:watch       # Watch mode testing
npm run test:coverage    # Generate coverage report

Package Management (for contributors)

npm run pack:check       # Verify tarball size before release
npm run commit           # Commitizen conventional commits
npm run release          # Release management with release-it
npm run prepare          # Husky git hooks setup

Release Checklist

npm run lint
npm run test:smoke -- --template standard
npm run pack:check

🔄 Migration Guide

From Create Next App

# 1. Create Starkon project
npx starkon my-app --template basic

# 2. Copy your existing code
cp -r old-project/src/app/* new-project/src/app/
cp -r old-project/components/* new-project/src/components/

# 3. Update imports
# Change: import { Button } from '../components/Button'
# To:     import { Button } from '@/components/core/button'

# 4. Install your additional dependencies
cd new-project
npm install your-packages

From Other Starters

1. Extract your custom components to src/components/
2. Move API logic to src/lib/services/
3. Update styling to use Tailwind classes
4. Add TypeScript types in src/lib/types/
5. Integrate with providers in src/providers/

Migrating Authentication

If you have existing auth:

1. Review Starkon's JWT flow in src/lib/services/authApiService.ts
2. Replace mock service with your API endpoints
3. Update token structure in sessionTokenManager.ts
4. Modify AuthProvider.tsx for your auth logic

🤝 Contributing

We welcome contributions to make Starkon even better!

Development Setup

# Clone repository
git clone https://github.com/zzafergok/starkon.git
cd starkon

# Install dependencies
npm install

# Start development
npm run dev

# Run tests
npm test

# Verify publish artifact
npm run pack:check

Creating New Templates

# 1. Add template metadata in cli/templates.js
# 2. Create templates/<name> and reuse shared or shared-full where appropriate
# 3. Test template generation
npx starkon test-app --template your-template

# 4. Update README.md with template documentation
# 5. Submit PR

Guidelines

• Code Quality: Follow ESLint and Prettier rules
• Testing: Add tests for new features
• Documentation: Update README for new features
• TypeScript: Maintain full type safety
• Conventional Commits: Use npm run commit for commits

📈 Performance

Bundle Analysis

# Analyze the repository app build
npm run analyze

Optimization Features

• Automatic Code Splitting - Route-based splitting
• Image Optimization - Next.js Image component
• Font Optimization - Google Fonts optimization
• Static Generation - ISG and SSG support
• Edge Runtime - Faster cold starts
• React Server Components - Reduced client bundle

🛠️ Troubleshooting

Common Issues

Build Errors:

# Clear Next.js cache
rm -rf .next

# Clear npm cache
npm cache clean --force

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

TypeScript Errors:

# Check types without building
npm run type-check

# Clear TypeScript cache
rm -rf node_modules/.cache

Authentication Issues:

# Check token in browser storage
# DevTools -> Application -> Session Storage -> tokens

# Clear all auth data
localStorage.clear()
sessionStorage.clear()

i18n Not Working:

# Check language detection priority:
# 1. localStorage 'language' key
# 2. Cookie 'language' key
# 3. URL parameter ?lang=en
# 4. Browser navigator.language
# 5. Default: 'tr'

# Force language
localStorage.setItem('language', 'en')

Component Not Found:

# Check import path uses @ alias
import { Button } from '@/components/core/button'  # ✅ Correct
import { Button } from '../components/core/button' # ❌ Wrong

# Verify tsconfig.json has paths configured:
# "@/*": ["./src/*"]

Getting Help

• 🐛 Bug Reports: GitHub Issues
• 💬 Questions: Discussions
• 📧 Contact: zafer@starkon.website
• 📚 Documentation: CLAUDE.md (for development)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Core Technologies:

• Next.js - The React framework for production
• Radix UI - Low-level accessible UI primitives
• Tailwind CSS - Utility-first CSS framework
• React Query - Powerful data synchronization
• Zustand - Lightweight state management

Inspiration:

• shadcn/ui - Component design patterns
• T3 Stack - TypeScript-first development
• Vercel Templates - Deployment optimization

📊 Stats

• 🎨 46 UI Components ready to use
• 🔐 Complete Auth System with JWT tokens & 5 auth flows
• 🌍 2 Languages supported (English, Turkish) with easy expansion
• 📱 6 Templates (3 interactive + 3 manual selection)
• 🪝 7 Custom Hooks for common patterns
• 🔌 5 Providers for app-wide state management
• ⚡ Interactive CLI generator with arrow key navigation
• 🚀 < 30 seconds from CLI to running app
• 🛠️ Production Ready - no additional setup needed
• 📦 React 19 & Next.js 16 - Latest versions