nexstruct 1.0.0

package/scaffold/generator.js

@@ -0,0 +1,409 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import ora from 'ora';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.resolve(__dirname, '../templates');
+
+const TEMPLATE_MAP = {
+  ui: {
+    shadcn: 'ui/shadcn',
+    mui: 'ui/mui',
+    antd: 'ui/antd',
+  },
+  state: {
+    redux: 'state/redux',
+    zustand: 'state/zustand',
+    context: 'state/context',
+  },
+  api: {
+    fetch: 'api/fetch',
+    axios: 'api/axios',
+    trpc: 'api/trpc',
+  },
+  auth: {
+    'next-auth': 'auth/next-auth',
+    clerk: 'auth/clerk',
+  },
+  forms: {
+    'react-hook-form': 'forms/react-hook-form',
+    'formik': 'forms/formik',
+  },
+};
+
+const DEPENDENCIES = {
+  shadcn: {
+    dependencies: ['class-variance-authority', 'clsx', 'tailwind-merge', 'lucide-react', 'react-hook-form', '@hookform/resolvers', 'zod', 'input-otp', 'react-hot-toast', 'react-phone-input-2', '@radix-ui/react-slot', '@radix-ui/react-dialog', '@radix-ui/react-dropdown-menu', '@radix-ui/react-select', '@radix-ui/react-tabs', '@radix-ui/react-toast', '@radix-ui/react-switch', '@radix-ui/react-checkbox', '@radix-ui/react-radio-group', '@radix-ui/react-tooltip', '@radix-ui/react-popover', '@radix-ui/react-scroll-area', '@radix-ui/react-avatar', '@radix-ui/react-progress', '@radix-ui/react-label', '@radix-ui/react-separator'],
+    devDependencies: ['tailwindcss', 'postcss', 'autoprefixer', 'tailwindcss-animate'],
+  },
+  mui: {
+    dependencies: ['@mui/material', '@mui/icons-material', '@emotion/react', '@emotion/styled', 'react-hot-toast'],
+  },
+  antd: {
+    dependencies: ['antd', '@ant-design/icons', 'dayjs', 'react-hot-toast'],
+  },
+  redux: {
+    dependencies: ['@reduxjs/toolkit', 'react-redux'],
+  },
+  zustand: {
+    dependencies: ['zustand'],
+  },
+  context: {},
+  fetch: {},
+  axios: {
+    dependencies: ['axios'],
+  },
+  trpc: {
+    dependencies: ['@trpc/server', '@trpc/client', '@trpc/react-query', '@tanstack/react-query', 'zod', 'superjson'],
+    devDependencies: ['@trpc/next'],
+  },
+  'next-auth': {
+    dependencies: ['next-auth'],
+  },
+  clerk: {
+    dependencies: ['@clerk/nextjs'],
+  },
+  'react-hook-form': {
+    dependencies: ['react-hook-form', '@hookform/resolvers', 'zod'],
+  },
+  formik: {
+    dependencies: ['formik', 'yup'],
+  },
+};
+
+export const generateProject = async (answers) => {
+  const { projectName, uiLibraries, stateManagement, apiLayer, auth, forms, includeExamples } = answers;
+
+  const outputDir = path.resolve(process.cwd(), projectName);
+
+  if (fs.existsSync(outputDir)) {
+    const { confirm } = await import('@inquirer/prompts');
+    const proceed = await confirm({
+      message: `Directory "${projectName}" already exists. Overwrite?`,
+      default: false,
+    });
+    if (!proceed) {
+      console.log(chalk.yellow('  Aborted.'));
+      process.exit(0);
+    }
+    fs.removeSync(outputDir);
+  }
+
+  const spinner = ora();
+
+  spinner.start('Forging base project...');
+  await fs.copy(path.join(TEMPLATES_DIR, 'nextjs-base'), outputDir);
+  spinner.succeed('Base project created');
+
+  spinner.start(`Adding UI libraries: ${uiLibraries.join(', ')}...`);
+  for (const lib of uiLibraries) {
+    const srcPath = path.join(TEMPLATES_DIR, TEMPLATE_MAP.ui[lib]);
+    if (fs.existsSync(srcPath)) {
+      await fs.copy(srcPath, outputDir);
+    }
+  }
+  spinner.succeed('UI libraries added');
+
+  spinner.start(`Adding state management: ${stateManagement.join(', ')}...`);
+  for (const sm of stateManagement) {
+    const srcPath = path.join(TEMPLATES_DIR, TEMPLATE_MAP.state[sm]);
+    if (fs.existsSync(srcPath)) {
+      await fs.copy(srcPath, outputDir);
+    }
+  }
+  spinner.succeed('State management added');
+
+  spinner.start(`Adding API layer: ${apiLayer.join(', ')}...`);
+  for (const api of apiLayer) {
+    const srcPath = path.join(TEMPLATES_DIR, TEMPLATE_MAP.api[api]);
+    if (fs.existsSync(srcPath)) {
+      await fs.copy(srcPath, outputDir);
+    }
+  }
+  spinner.succeed('API layer added');
+
+  if (auth !== 'none') {
+    spinner.start(`Adding auth: ${auth}...`);
+    const srcPath = path.join(TEMPLATES_DIR, TEMPLATE_MAP.auth[auth]);
+    if (fs.existsSync(srcPath)) {
+      await fs.copy(srcPath, outputDir);
+    }
+    spinner.succeed('Auth added');
+  }
+
+  if (forms !== 'none') {
+    spinner.start(`Adding form handling: ${forms}...`);
+    const srcPath = path.join(TEMPLATES_DIR, TEMPLATE_MAP.forms[forms]);
+    if (fs.existsSync(srcPath)) {
+      await fs.copy(srcPath, outputDir);
+    }
+    spinner.succeed('Form handling added');
+  }
+
+  spinner.start('Copying shared utilities...');
+  const sharedPath = path.join(TEMPLATES_DIR, 'shared');
+  if (fs.existsSync(sharedPath)) {
+    await fs.copy(sharedPath, outputDir);
+  }
+  spinner.succeed('Shared utilities added');
+
+  if (!includeExamples) {
+    spinner.start('Removing example files...');
+    const examplePaths = [
+      path.join(outputDir, 'src/app/page.tsx'),
+      path.join(outputDir, 'src/app/examples'),
+    ];
+    for (const p of examplePaths) {
+      if (fs.existsSync(p)) {
+        await fs.remove(p);
+      }
+    }
+    spinner.succeed('Examples removed');
+  }
+
+  spinner.start('Generating package.json...');
+  await generatePackageJson(outputDir, { projectName, uiLibraries, stateManagement, apiLayer, auth, forms, dualMode: answers.dualMode });
+  spinner.succeed('package.json generated');
+
+  spinner.start('Generating tsconfig.json...');
+  await generateTsconfig(outputDir);
+  spinner.succeed('tsconfig.json generated');
+
+  spinner.start('Generating provider composition...');
+  await generateProviders(outputDir, answers);
+  spinner.succeed('Provider composition generated');
+
+  spinner.start('Generating project README...');
+  await generateReadme(outputDir, answers);
+  spinner.succeed('README generated');
+
+  console.log(chalk.dim(`\n  ───────────────────────────────────`));
+  console.log(chalk.bold(`  Next steps:`));
+  console.log(chalk.cyan(`  cd ${projectName}`));
+  console.log(chalk.cyan(`  npm install`));
+  console.log(chalk.cyan(`  npm run dev`));
+  console.log(chalk.dim(`  ───────────────────────────────────`));
+};
+
+const generatePackageJson = async (outputDir, options) => {
+  const { projectName, uiLibraries, stateManagement, apiLayer, auth, forms, dualMode } = options;
+
+  const allDeps = {};
+  const allDevDeps = {
+    'typescript': '^5.4.0',
+    '@types/node': '^20.0.0',
+    '@types/react': '^18.3.0',
+    '@types/react-dom': '^18.3.0',
+    'eslint': '^9.0.0',
+    'eslint-config-next': '^15.0.0',
+    '@eslint/eslintrc': '^3.0.0',
+  };
+
+  const mergeDeps = (selected, category) => {
+    for (const item of selected) {
+      const config = DEPENDENCIES[item];
+      if (config) {
+        if (config.dependencies) {
+          for (const dep of config.dependencies) {
+            allDeps[dep] = '*';
+          }
+        }
+        if (config.devDependencies) {
+          for (const dep of config.devDependencies) {
+            allDevDeps[dep] = '*';
+          }
+        }
+      }
+    }
+  };
+
+  mergeDeps(uiLibraries, 'ui');
+  mergeDeps(stateManagement, 'state');
+  mergeDeps(apiLayer, 'api');
+  if (auth !== 'none') mergeDeps([auth], 'auth');
+  if (forms !== 'none') mergeDeps([forms], 'forms');
+  if (dualMode) allDeps['next-themes'] = '*';
+
+  const packageJson = {
+    name: projectName,
+    version: '0.1.0',
+    private: true,
+    scripts: {
+      dev: 'next dev',
+      build: 'next build',
+      start: 'next start',
+      lint: 'next lint',
+      typecheck: 'tsc --noEmit',
+    },
+    dependencies: {
+      'next': '^15.0.0',
+      'react': '^18.3.0',
+      'react-dom': '^18.3.0',
+      ...allDeps,
+    },
+    devDependencies: {
+      ...allDevDeps,
+    },
+  };
+
+  await fs.writeJson(path.join(outputDir, 'package.json'), packageJson, { spaces: 2 });
+};
+
+const generateTsconfig = async (outputDir) => {
+  const tsconfig = {
+    compilerOptions: {
+      target: 'ES2017',
+      lib: ['dom', 'dom.iterable', 'esnext'],
+      allowJs: true,
+      skipLibCheck: true,
+      strict: true,
+      noEmit: true,
+      esModuleInterop: true,
+      module: 'esnext',
+      moduleResolution: 'bundler',
+      resolveJsonModule: true,
+      isolatedModules: true,
+      jsx: 'preserve',
+      incremental: true,
+      plugins: [{ name: 'next' }],
+      paths: { '@/*': ['./src/*'] },
+    },
+    include: ['next-env.d.ts', '**/*.ts', '**/*.tsx', '.next/types/**/*.ts'],
+    exclude: ['node_modules'],
+  };
+
+  await fs.writeJson(path.join(outputDir, 'tsconfig.json'), tsconfig, { spaces: 2 });
+};
+
+const generateProviders = async (outputDir, answers) => {
+  const { uiLibraries, stateManagement, apiLayer, auth, dualMode } = answers;
+
+  const providerImports = [];
+  const providerComponents = [];
+
+  providerImports.push("import { ToastProvider } from '@/providers/toast.provider';");
+  providerComponents.push('ToastProvider');
+
+  if (dualMode) {
+    providerImports.push("import { ThemeProvider } from '@/providers/theme.provider';");
+    providerComponents.push('ThemeProvider');
+  }
+
+  if (uiLibraries.includes('mui')) {
+    providerImports.push("import { MuiProvider } from '@/providers/mui.provider';");
+    providerComponents.push('MuiProvider');
+  }
+  if (uiLibraries.includes('antd')) {
+    providerImports.push("import { AntdProvider } from '@/providers/antd.provider';");
+    providerComponents.push('AntdProvider');
+  }
+  if (stateManagement.includes('redux')) {
+    providerImports.push("import { ReduxProvider } from '@/providers/redux.provider';");
+    providerComponents.push('ReduxProvider');
+  }
+  if (apiLayer.includes('trpc')) {
+    providerImports.push("import { TrpcProvider } from '@/providers/trpc.provider';");
+    providerComponents.push('TrpcProvider');
+  }
+  if (auth === 'next-auth') {
+    providerImports.push("import { AuthProvider as NextAuthProvider } from '@/providers/session.provider';");
+    providerComponents.push('NextAuthProvider');
+  }
+  if (auth === 'clerk') {
+    providerImports.push("import { AuthProvider as ClerkAuthProvider } from '@/providers/auth.provider';");
+    providerComponents.push('ClerkAuthProvider');
+  }
+
+  const nested = providerComponents.reduce(
+    (children, provider) => `    <${provider}>${children}    </${provider}>`,
+    '      {children}\n'
+  );
+
+  const content = `'use client';
+${providerImports.join('\n')}
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+${nested}
+  );
+}
+`;
+
+  const providersDir = path.join(outputDir, 'src/providers');
+  await fs.ensureDir(providersDir);
+  await fs.writeFile(path.join(providersDir, 'index.tsx'), content);
+
+  const layoutPath = path.join(outputDir, 'src/app/layout.tsx');
+  if (fs.existsSync(layoutPath)) {
+    let layout = await fs.readFile(layoutPath, 'utf-8');
+    layout = layout.replace(
+      "import './globals.css';",
+      "import './globals.css';\nimport { Providers } from '@/providers';"
+    );
+    layout = layout.replace(
+      '<Sidebar>{children}</Sidebar>',
+      '<Providers><Sidebar>{children}</Sidebar></Providers>'
+    );
+    await fs.writeFile(layoutPath, layout);
+  }
+};
+
+const generateReadme = async (outputDir, answers) => {
+  const { projectName, uiLibraries, stateManagement, apiLayer, auth, forms } = answers;
+
+  const readme = `# ${projectName}
+
+Scaffolded with ⚒️ **Nexstruct**
+
+## Stack
+
+- **Framework:** Next.js 15 + TypeScript
+- **UI Library:** ${uiLibraries.join(', ')}
+- **State Management:** ${stateManagement.join(', ')}
+- **API Layer:** ${apiLayer.join(', ')}
+- **Auth:** ${auth}
+- **Forms:** ${forms}
+
+## Getting Started
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+## Conventions
+
+Files follow the \`[name].[category].ts\` 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 |
+
+## Project Structure
+
+\`\`\`
+src/
+├── app/          # Next.js App Router pages
+├── components/   # Reusable UI components
+│   └── ui/       # Base UI primitives
+├── hooks/        # Custom React hooks
+├── lib/          # Library configs
+├── store/        # State management
+├── api/          # API layer
+├── auth/         # Authentication
+├── forms/        # Form handling
+└── types/        # TypeScript types
+\`\`\`
+`;
+
+  await fs.writeFile(path.join(outputDir, 'README.md'), readme);
+};

package/scaffold/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+import chalk from 'chalk';
+import { askPrompts } from './prompts.js';
+import { generateProject } from './generator.js';
+
+const main = async () => {
+  console.log(chalk.bold.cyan('\n  ⚒️  NEXSTRUCT\n'));
+  console.log(chalk.dim('  Scaffold your production-ready Next.js project\n'));
+
+  const answers = await askPrompts();
+  await generateProject(answers);
+
+  console.log(chalk.green.bold('\n  ✓ Project scaffolded successfully!\n'));
+};
+
+main().catch((err) => {
+  console.error(chalk.red('  ✗ Error:'), err.message);
+  process.exit(1);
+});

package/scaffold/prompts.js

@@ -0,0 +1,108 @@
+import { input, select, checkbox, confirm } from '@inquirer/prompts';
+import fs from 'fs';
+import path from 'path';
+
+/** Generate a related default project name from selected tech choices */
+const deriveDefaultName = ({ uiLibraries, stateManagement }) => {
+  const uiLabel = uiLibraries[0] || 'app';
+  const stateLabel = stateManagement[0] || '';
+  const parts = [uiLabel, stateLabel, 'app'].filter(Boolean);
+  return parts.join('-');
+};
+
+/** Check if a directory with the given name already exists in cwd */
+const isDirectoryTaken = (name) => {
+  try {
+    return fs.statSync(path.resolve(process.cwd(), name)).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+export const askPrompts = async () => {
+  const uiLibraries = await checkbox({
+    message: 'Select UI libraries:',
+    choices: [
+      { name: 'shadcn/ui (with Tailwind CSS)', value: 'shadcn', checked: true },
+      { name: 'Material UI (MUI)', value: 'mui' },
+      { name: 'Ant Design', value: 'antd' },
+    ],
+    required: true,
+  });
+
+  const stateManagement = await checkbox({
+    message: 'Select state management:',
+    choices: [
+      { name: 'Redux Toolkit (with RTK Query)', value: 'redux' },
+      { name: 'Zustand', value: 'zustand', checked: true },
+      { name: 'React Context + useReducer', value: 'context' },
+    ],
+    required: true,
+  });
+
+  const apiLayer = await checkbox({
+    message: 'Select API layer:',
+    choices: [
+      { name: 'Fetch API (built-in)', value: 'fetch', checked: true },
+      { name: 'Axios', value: 'axios' },
+      { name: 'tRPC', value: 'trpc' },
+    ],
+    required: true,
+  });
+
+  const auth = await select({
+    message: 'Select authentication:',
+    choices: [
+      { name: 'None', value: 'none' },
+      { name: 'NextAuth.js', value: 'next-auth' },
+      { name: 'Clerk', value: 'clerk' },
+    ],
+  });
+
+  const forms = await select({
+    message: 'Select form handling:',
+    choices: [
+      { name: 'None', value: 'none' },
+      { name: 'React Hook Form', value: 'react-hook-form' },
+      { name: 'Formik', value: 'formik' },
+    ],
+  });
+
+  const dualMode = await confirm({
+    message: 'Enable dark/light mode toggle?',
+    default: true,
+  });
+
+  const includeExamples = await confirm({
+    message: 'Include example components and pages?',
+    default: true,
+  });
+
+  // Project name comes last so default can be derived from selections
+  const defaultName = deriveDefaultName({ uiLibraries, stateManagement });
+
+  const projectName = await input({
+    message: 'Project name:',
+    default: defaultName,
+    validate: (v) => {
+      if (!/^[a-z0-9-]+$/.test(v)) {
+        return 'Use lowercase letters, numbers, and hyphens only';
+      }
+      if (isDirectoryTaken(v)) {
+        return `Directory "${v}" already exists. Choose a unique name`;
+      }
+      return true;
+    },
+  });
+
+  return {
+    projectName,
+    uiLibraries,
+    stateManagement,
+    apiLayer,
+    auth,
+    forms,
+    dualMode,
+    includeExamples,
+  };
+};

package/templates/api/axios/src/api/axios/client.api.ts

@@ -0,0 +1,30 @@
+import axios, { type AxiosInstance, type AxiosRequestConfig } from 'axios';
+
+const createClient = (config?: AxiosRequestConfig): AxiosInstance => {
+  const client = axios.create({
+    baseURL: process.env.NEXT_PUBLIC_API_URL || '/api',
+    headers: { 'Content-Type': 'application/json' },
+    ...config,
+  });
+
+  client.interceptors.response.use(
+    (response) => response,
+    (error) => {
+      if (error.response) {
+        throw new ApiError(error.response.status, error.response.data?.message || error.message);
+      }
+      throw error;
+    }
+  );
+
+  return client;
+};
+
+export class ApiError extends Error {
+  constructor(public status: number, message: string) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+
+export const api = createClient();

package/templates/api/axios/src/api/axios/users.api.ts

@@ -0,0 +1,15 @@
+import { api } from './client.api';
+
+export interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+export const usersApi = {
+  list: (params?: { page?: number }) => api.get<User[]>('/users', { params }),
+  get: (id: string) => api.get<User>(`/users/${id}`),
+  create: (data: Partial<User>) => api.post<User>('/users', data),
+  update: (id: string, data: Partial<User>) => api.put<User>(`/users/${id}`, data),
+  delete: (id: string) => api.delete<void>(`/users/${id}`),
+};

package/templates/api/fetch/src/api/fetch/client.api.ts

@@ -0,0 +1,68 @@
+type RequestOptions = Omit<RequestInit, 'body'> & {
+  body?: unknown;
+  params?: Record<string, string>;
+};
+
+class ApiClient {
+  private baseUrl: string;
+
+  constructor(baseUrl?: string) {
+    this.baseUrl = baseUrl || process.env.NEXT_PUBLIC_API_URL || '/api';
+  }
+
+  private async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { body, params, ...init } = options;
+    let url = `${this.baseUrl}${path}`;
+
+    if (params) {
+      const searchParams = new URLSearchParams(params);
+      url += `?${searchParams}`;
+    }
+
+    const headers: HeadersInit = {
+      'Content-Type': 'application/json',
+      ...init.headers,
+    };
+
+    const response = await fetch(url, {
+      ...init,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    if (!response.ok) {
+      throw new ApiError(response.status, await response.text());
+    }
+
+    return response.json();
+  }
+
+  get<T>(path: string, options?: RequestOptions) {
+    return this.request<T>(path, { ...options, method: 'GET' });
+  }
+
+  post<T>(path: string, body?: unknown, options?: RequestOptions) {
+    return this.request<T>(path, { ...options, method: 'POST', body });
+  }
+
+  put<T>(path: string, body?: unknown, options?: RequestOptions) {
+    return this.request<T>(path, { ...options, method: 'PUT', body });
+  }
+
+  patch<T>(path: string, body?: unknown, options?: RequestOptions) {
+    return this.request<T>(path, { ...options, method: 'PATCH', body });
+  }
+
+  delete<T>(path: string, options?: RequestOptions) {
+    return this.request<T>(path, { ...options, method: 'DELETE' });
+  }
+}
+
+export class ApiError extends Error {
+  constructor(public status: number, message: string) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+
+export const api = new ApiClient();

package/templates/api/fetch/src/api/fetch/users.api.ts

@@ -0,0 +1,15 @@
+import { api } from './client.api';
+
+export interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+export const usersApi = {
+  list: (params?: { page?: string }) => api.get<User[]>('/users', { params }),
+  get: (id: string) => api.get<User>(`/users/${id}`),
+  create: (data: Partial<User>) => api.post<User>('/users', data),
+  update: (id: string, data: Partial<User>) => api.put<User>(`/users/${id}`, data),
+  delete: (id: string) => api.delete<void>(`/users/${id}`),
+};

package/templates/api/trpc/src/api/trpc/client.api.ts

@@ -0,0 +1,4 @@
+import { createTRPCReact } from '@trpc/react-query';
+import type { AppRouter } from './router.api';
+
+export const trpc = createTRPCReact<AppRouter>();

package/templates/api/trpc/src/api/trpc/router.api.ts

@@ -0,0 +1,15 @@
+import { initTRPC } from '@trpc/server';
+import superjson from 'superjson';
+import { z } from 'zod';
+
+const t = initTRPC.create({ transformer: superjson });
+
+export const appRouter = t.router({
+  hello: t.procedure
+    .input(z.object({ name: z.string() }))
+    .query(({ input }) => {
+      return { greeting: `Hello, ${input.name}!` };
+    }),
+});
+
+export type AppRouter = typeof appRouter;

package/templates/api/trpc/src/api/trpc/server.client.api.ts

@@ -0,0 +1,4 @@
+import { createTRPCContext } from '@trpc/next';
+import type { AppRouter } from './router.api';
+
+export const trpcServer = createTRPCContext<AppRouter>();