Getting Started

npx nexstruct

No install needed. Run the command, answer a few prompts, and your project is ready.

Why Nexstruct?

Setting up a Next.js project with the right stack takes time. Nexstruct does it in seconds — with production-ready code, not boilerplate.

The Problem

You start a new project and spend hours:

• Configuring TypeScript, ESLint, Tailwind
• Setting up your UI library and theme provider
• Wiring up state management, auth, forms
• Building reusable components you've built ten times before
• Writing the same utility functions from scratch

The Solution

Nexstruct gives you all of this out of the box:

| What You Need | What Nexstruct Gives You | |---------------|--------------------------| | UI Components | 24+ CustomField types — text, number, select, date, file upload, rich text, OTP, phone, and more | | Form Handling | Dual-mode fields that work with or without react-hook-form — no refactoring needed | | State Management | Redux Toolkit, Zustand, or React Context — fully configured with providers | | Authentication | NextAuth.js, Clerk, or JWT Auth (Custom) with 4 token strategies — you choose | | API Layer | Fetch, Axios, or tRPC — with typed clients and error handling | | Toast Notifications | Unified toast system — success, error, loading, custom — wired into Providers | | Theme Toggle | Dark/light mode with next-themes — already in the layout | | Type Safety | Strict TypeScript throughout — no any escaping into your code |

Demo

$ npx nexstruct
  ⚒️  NEXSTRUCT

  Scaffold your production-ready Next.js project

? Select UI libraries:  (Press <space> to select)
  ◉ shadcn/ui (with Tailwind CSS)
  ◯ Material UI (MUI)
  ◯ Ant Design

? Select state management:
  ◯ Redux Toolkit (with RTK Query)
  ◉ Zustand
  ◯ React Context + useReducer

? Select API layer:
  ◉ Fetch API (built-in)
  ◯ Axios
  ◯ tRPC

? Select authentication:
  ◯ None
  ◯ NextAuth.js
  ◯ Clerk
  ◉ JWT Auth (Custom)

? Select token strategy:
  ◉ Cookie-Based (Recommended)
  ◯ Memory + Cookie
  ◯ LocalStorage
  ◯ SessionStorage

? Select form handling:  (None / react-hook-form / Formik)

? Project name:  my-app

  ✓ Project scaffolded successfully!

  ───────────────────────────────────
  Next steps:
  cd my-app
  npm install
  npm run dev
  ───────────────────────────────────

That's it. Your project is ready with a full component system, providers wired up, and example pages to show you how everything works.

What's Inside

my-app/
├── src/
│   ├── app/              # App Router pages & layouts
│   │   ├── layout.tsx    # Root layout with Providers
│   │   ├── page.tsx      # Home page with live clock
│   │   └── examples/     # Example components (optional)
│   ├── components/
│   │   ├── ui/           # Base primitives (button, card, dialog, etc.)
│   │   ├── common/       # ActionButton, DialogWrapper, DynamicTable, Pagination
│   │   └── fields/       # CustomField.* (24 types for shadcn)
│   ├── providers/        # Composable provider wrappers
│   ├── lib/              # Utilities, types, API clients
│   │   ├── token-storage.ts   # Auth token storage strategy
│   │   └── api-client.ts      # Axios/Fetch with auto-refresh
│   ├── hooks/            # Custom React hooks
│   ├── store/            # State management (if selected)
│   ├── api/              # API layer (if selected)
│   │   └── auth/         # Auth API calls & types (if JWT Auth)
│   ├── auth/             # Auth (if NextAuth/Clerk)
│   └── forms/            # Form handling (if selected)
├── .env.local            # Environment variables
├── next.config.ts
├── tsconfig.json
└── package.json

Component System

Nexstruct doesn't just scaffold files — it gives you a reusable component system that scales:

UI Primitives — button, badge, card, dialog, input, label, select, form, switch, checkbox, radio-group, textarea, table, tooltip, popover, scroll-area, avatar, sheet, dropdown-menu, tabs, progress, separator, input-otp.

CustomField System — 24+ field types with dual-mode support:

| Field | Features | |-------|----------| | CustomField.Text | Left/right icons, array splitting | | CustomField.Number | Integer/float mode, scroll prevention, min=0 | | CustomField.Password | Show/hide toggle, strength validation | | CustomField.PhoneNumber | Country dropdown, flag, search, maskable view | | CustomField.SingleSelectField | Loading/empty states | | CustomField.SelectField | Multi-select, search, avatars, tags | | CustomField.DatePickerField | Date picker with calendar | | CustomField.UploadProfilePicture | Avatar upload with preview | | CustomField.RichTextEditor | Rich text editing | | ...and 15+ more | |

Every field works two ways:

// With react-hook-form — validation, errors, form state
<CustomField.Text form={form} name="username" label="Username" />

// Without form library — standalone, controlled input
<CustomField.Text value={value} onChange={setValue} label="Username" />

No refactoring. No wrapper components. Same API, both modes.

Project Structure

src/
├── app/              # Next.js App Router pages & layouts
├── components/       # Reusable UI components
│   ├── ui/           # Base UI primitives
│   ├── common/       # Common components (navbar, fields, etc.)
│   └── fields/       # CustomField system
├── hooks/            # Custom React hooks
├── lib/              # Utilities & configurations
│   └── utils.util.ts # cn(), formatDate(), maskString(), passwordRules, etc.
├── providers/        # Provider wrappers (auto-generated based on selection)
├── store/            # State management (Redux/Zustand)
├── api/              # API layer (Fetch/Axios/tRPC)
├── auth/             # Authentication (NextAuth/Clerk)
├── forms/            # Form handling (react-hook-form/Formik)
└── types/            # TypeScript types

File Naming Convention

| Extension | Type | |-----------|------| | .component.tsx | UI components | | .store.ts | State management | | .api.ts | API layer | | .hook.ts | React hooks | | .service.ts | Auth/services | | .util.ts | Utilities | | .type.ts | TypeScript types | | .provider.tsx | Context providers |

Authentication Options

Nexstruct offers 4 authentication options:

| Option | Description | Token Control | |--------|-------------|---------------| | None | No authentication | — | | NextAuth.js | Managed session with OAuth + Credentials | Library handles | | Clerk | Managed auth with social + password | Library handles | | JWT Auth (Custom) | Full control with 4 token strategies | You control |

JWT Auth Token Strategies

When you select JWT Auth (Custom), choose a token storage strategy:

| Strategy | Security | Persistence | Best For | |----------|----------|-------------|----------| | Cookie-Based ⭐ | ✅ XSS-proof | ✅ Server-managed | Production apps | | Memory + Cookie | ✅ Refresh safe | ⚠️ Access lost on refresh | SPAs needing token access | | LocalStorage | ❌ XSS vulnerable | ✅ Permanent | Prototypes only | | SessionStorage | ❌ XSS vulnerable | ⚠️ Tab-only | Low-risk apps |

What's Included with JWT Auth

• Login, Register, Logout
• Access & Refresh token flow
• Forgot/Reset/Change password
• Profile management
• Auto-refresh on 401
• Zod validation schemas
• Integration with Zustand/Redux/Context

Backend Support

The JWT auth frontend works with any backend (Node.js, Python, Go, etc.):

# .env.local
NEXT_PUBLIC_API_URL=http://localhost:3001
ACCESS_TOKEN_SECRET=your-secret-min-32-chars
REFRESH_TOKEN_SECRET=your-secret-min-32-chars

Required backend endpoints:

| Endpoint | Method | Description | |----------|--------|-------------| | /auth/register | POST | Create account | | /auth/login | POST | Sign in | | /auth/logout | POST | Sign out | | /auth/refresh | POST | Refresh token | | /auth/me | GET | Current user |

Documentation

Visit https://nexstruct.vercel.app for the full documentation, including:

• Auth Strategies Guide — Detailed guide on token storage strategies
• Framework Guides — shadcn/ui, MUI, Ant Design
• Component Lab — Live demos of all components

Updating Existing Projects

After Nexstruct releases new templates, you can update your project without losing customizations:

npx nexstruct update

The update command:

• Detects changes between your project and the latest templates
• Skips files you modified — only updates untouched files
• Shows a preview before applying any changes
• Adds new files that weren't in your original scaffold
• Preserves your code — conflicts are flagged and optional

Cleanup

When you're ready to remove example/demo files:

npm run cleanup

Each step asks for your permission before making any changes.

License

MIT