create-next-structure 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2026 MD. Sifat Islam
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+
+# create-next-structure
+
+CLI tool to scaffold a **Next.js + Redux Toolkit** project structure with auth, RTK Query, and a ready-to-use template.
+
+## ✅ Features
+
+- Next.js App Router layout
+- Redux Toolkit + RTK Query pre-configured
+- Auth flow helpers and protected routes
+- Reusable UI components and layout shell
+- Template documentation included
+
+## 📦 Install
+
+```bash
+npm install -g create-next-structure
+```
+
+## 🚀 Usage
+
+```bash
+create-next-structure my-app
+```
+
+Then:
+
+```bash
+cd my-app
+npm install
+npm run dev
+```
+
+## 🧩 Template docs
+
+After generation, read:
+
+- `docs/README.md` (template usage overview)
+- `docs/PROJECT_STRUCTURE.md`
+- `docs/API_INTEGRATION.md`
+- `docs/ARCHITECTURE.md`
+- `docs/EXAMPLES.md`
+
+## 🔧 Notes
+
+- Make sure you create `.env.local` using `.env.template` and set `NEXT_PUBLIC_API_URL`.
+- Protected routes live under `app/(dashboard)`.
+
+## 📄 License
+
+ISC

package/bin/index.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+import fs from "fs-extra";
+import path from "path";
+import { fileURLToPath } from "url";
+import chalk from "chalk";
+import ora from "ora";
+// Update notifier
+import updateNotifier from "update-notifier";
+import pkg from "../package.json" assert { type: "json" };
+
+const notifier = updateNotifier({
+  pkg,
+  updateCheckInterval: 1000 * 60 * 60, // 1 hour
+});
+
+notifier.notify();
+
+if (notifier.update) {
+  console.log(
+    chalk.yellow(`Update available ${pkg.version} → ${notifier.update.latest}`),
+  );
+  console.log(chalk.blue(`Run npm install -g ${pkg.name}@latest to update.\n`));
+}
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// project name --> from user arg
+const projectName = (process.argv[2] || "").trim();
+
+// check if project name is provided
+if (!projectName) {
+  console.log(chalk.red("Please provide a project name"));
+  console.log(chalk.blue("Usage: create-next-structure <project-name>"));
+  process.exit(1);
+}
+
+// basic validation for folder name
+const invalidNameChars = /[<>:"/\\|?*\x00-\x1F]/;
+if (invalidNameChars.test(projectName)) {
+  console.log(chalk.red("Invalid project name. Avoid special characters."));
+  process.exit(1);
+}
+
+// Dirs
+const targetDir = path.join(process.cwd(), projectName);
+const templateDir = path.join(__dirname, "../templates");
+
+// Create project function
+async function createProject() {
+  const spinner = ora("Creating project structure...").start();
+
+  try {
+    // Check template dir exists
+    const templateExists = await fs.pathExists(templateDir);
+    if (!templateExists) {
+      spinner.fail("Template folder not found");
+      console.error(chalk.red(`Missing template at: ${templateDir}`));
+      process.exit(1);
+    }
+
+    // Prevent overwrite
+    const targetExists = await fs.pathExists(targetDir);
+    if (targetExists) {
+      spinner.fail("Target folder already exists");
+      console.error(chalk.red(`Folder already exists: ${targetDir}`));
+      process.exit(1);
+    }
+
+    // copy template files to target dir
+    await fs.copy(templateDir, targetDir);
+
+    spinner.succeed("Project structure created successfully!");
+    console.log(
+      chalk.green(`Your Next.js project "${projectName}" has been created!`),
+    );
+    console.log(
+      chalk.blue(`Navigate to the project directory: cd ${projectName}`),
+    );
+    console.log(chalk.blue("Install dependencies: npm install"));
+    console.log(chalk.blue("Start development server: npm run dev"));
+  } catch (err) {
+    spinner.fail("Failed to create project structure");
+    console.error(chalk.red(err));
+    process.exit(1);
+  }
+}
+
+createProject();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "create-next-structure",
+  "version": "1.0.0",
+  "main": "index.js",
+  "bin": {
+    "create-next-structure": "bin/index.js"
+  },
+  "type": "module",
+  "description": "Scaffold a Next.js + Redux Toolkit project structure with auth and RTK Query.",
+  "keywords": [
+    "nextjs",
+    "redux",
+    "rtk-query",
+    "template",
+    "scaffold",
+    "cli",
+    "starter"
+  ],
+  "author": "MD. Sifat Islam",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stackmatrixdev/create-next-structure.git"
+  },
+  "homepage": "https://github.com/stackmatrixdev/create-next-structure#readme",
+  "bugs": {
+    "url": "https://github.com/stackmatrixdev/create-next-structure/issues"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^9.2.0",
+    "ora": "^7.0.1",
+    "update-notifier": "^7.3.1"
+  }
+}

package/templates/.env.template

@@ -0,0 +1,36 @@
+# Environment Variables Template
+
+# Copy this file to .env.local and fill in your values
+# .env.local is ignored by git for security
+
+# ===========================================
+# API Configuration
+# ===========================================
+
+# Backend API Base URL (REQUIRED)
+# Development: http://localhost:5000/api/v1
+# Production: https://your-api.com/api/v1
+NEXT_PUBLIC_API_URL=http://localhost:5000/api/v1
+
+# ===========================================
+# Optional Configuration
+# ===========================================
+
+# App Name
+NEXT_PUBLIC_APP_NAME="My App"
+
+# App Version
+NEXT_PUBLIC_APP_VERSION="1.0.0"
+
+# Enable Debug Mode (show console logs)
+NEXT_PUBLIC_DEBUG_MODE=false
+
+
+# ===========================================
+# Notes
+# ===========================================
+
+# 1. NEXT_PUBLIC_ prefix makes variables available in browser
+# 2. Variables without prefix are server-side only
+# 3. Never commit .env.local to version control
+# 4. Update values based on your environment

package/templates/app/(dashboard)/dashboard/page.jsx

@@ -0,0 +1,40 @@
+/**
+ * Dashboard Page (Redux Version)
+ * Responsibility: Main dashboard view with Redux state
+ *
+ * FEATURES:
+ * - Uses Redux to access user data
+ * - Shows current user information
+ */
+
+"use client";
+
+import { useSelector } from "react-redux";
+import { selectCurrentUser } from "@/store/slices/authSlice";
+
+export default function DashboardPage() {
+  const user = useSelector(selectCurrentUser);
+
+  return (
+    <div className="dashboard">
+      <h1>Dashboard</h1>
+      <p>Welcome, {user?.email || user?.name || "User"}</p>
+      <div className="user-info">
+        {user && (
+          <>
+            <p>
+              <strong>Email:</strong> {user.email}
+            </p>
+            <p>
+              <strong>Role:</strong> {user.role || "N/A"}
+            </p>
+            <p>
+              <strong>ID:</strong> {user.id || user._id}
+            </p>
+          </>
+        )}
+      </div>
+      {/* Add dashboard content here */}
+    </div>
+  );
+}

package/templates/app/(dashboard)/layout.jsx

@@ -0,0 +1,24 @@
+/**
+ * Dashboard Layout
+ * Responsibility: Protected layout with header and sidebar
+ */
+
+"use client";
+
+import { Header } from "@/components/layout/Header";
+import { Sidebar } from "@/components/layout/Sidebar";
+import { withAuth } from "@/components/auth/withAuth";
+
+function DashboardLayout({ children }) {
+  return (
+    <div className="app-layout">
+      <Header />
+      <div className="layout-content">
+        <Sidebar />
+        <main className="main-content">{children}</main>
+      </div>
+    </div>
+  );
+}
+
+export default withAuth(DashboardLayout);

package/templates/app/(dashboard)/users/page.jsx

@@ -0,0 +1,64 @@
+/**
+ * Users Page (Redux Version with RTK Query)
+ * Responsibility: Display and manage users using RTK Query
+ *
+ * FEATURES:
+ * - Automatic data fetching with RTK Query
+ * - Built-in caching and refetching
+ * - Loading and error states handled automatically
+ * - No manual useState or useEffect needed!
+ *
+ * USAGE EXAMPLE:
+ * - Data is automatically fetched when component mounts
+ * - Refetch manually: refetch()
+ * - Access loading state: isLoading
+ * - Access error state: error
+ */
+
+"use client";
+
+import { useGetUsersQuery } from "@/store/api/userApi";
+import { Loading, ErrorDisplay } from "@/components/ui";
+
+export default function UsersPage() {
+  // RTK Query automatically handles fetching, caching, and state
+  const { data, isLoading, error, refetch } = useGetUsersQuery({
+    page: 1,
+    limit: 10,
+  });
+
+  if (isLoading) return <Loading />;
+  if (error)
+    return (
+      <ErrorDisplay
+        error={error.data?.message || "Failed to load users"}
+        onRetry={refetch}
+      />
+    );
+
+  const users = data?.users || data?.data || [];
+
+  return (
+    <div className="users-page">
+      <div className="users-header">
+        <h1>Users</h1>
+        <button onClick={refetch}>Refresh</button>
+      </div>
+      <div className="users-list">
+        {users.length === 0 ? (
+          <p>No users found</p>
+        ) : (
+          users.map((user) => (
+            <div key={user._id || user.id} className="user-card">
+              <p>
+                <strong>{user.name || user.email}</strong>
+              </p>
+              <p>{user.email}</p>
+              <span>{user.role || "User"}</span>
+            </div>
+          ))
+        )}
+      </div>
+    </div>
+  );
+}

package/templates/app/globals.css

@@ -0,0 +1,14 @@
+/**
+ * Global Styles
+ * Add your global CSS/styling framework here
+ */
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+    sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* Add your component styles or import CSS framework */

package/templates/app/layout.jsx

@@ -0,0 +1,25 @@
+/**
+ * Root Layout
+ * Responsibility: Main application layout wrapper with Redux Provider
+ */
+
+import { Inter } from "next/font/google";
+import { ReduxProvider } from "@/store/ReduxProvider";
+import "./globals.css";
+
+const inter = Inter({ subsets: ["latin"] });
+
+export const metadata = {
+  title: "App Template - Redux",
+  description: "Next.js starter template with Redux Toolkit & RTK Query",
+};
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body className={inter.className}>
+        <ReduxProvider>{children}</ReduxProvider>
+      </body>
+    </html>
+  );
+}

package/templates/app/login/page.jsx

@@ -0,0 +1,69 @@
+/**
+ * Login Page (Redux Version)
+ * Responsibility: User login form with Redux & RTK Query
+ *
+ * FEATURES:
+ * - Uses Redux for state management
+ * - Uses RTK Query for API calls
+ * - Auto-redirects on successful login
+ * - Protected with withPublic HOC
+ */
+
+"use client";
+
+import { useState } from "react";
+import { useAuth } from "@/hooks/useAuth";
+import { withPublic } from "@/components/auth/withPublic";
+import { Button, Input } from "@/components/ui";
+
+function LoginPage() {
+  const { login, isLoading } = useAuth();
+  const [formData, setFormData] = useState({ email: "", password: "" });
+  const [error, setError] = useState("");
+
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    setError("");
+
+    try {
+      await login(formData);
+      // Auto-redirects to /dashboard on success
+    } catch (err) {
+      setError(err?.data?.message || "Login failed. Please try again.");
+    }
+  };
+
+  return (
+    <div className="auth-page">
+      <div className="auth-card">
+        <h1>Login</h1>
+        <form onSubmit={handleSubmit}>
+          <Input
+            label="Email"
+            type="email"
+            value={formData.email}
+            onChange={(e) =>
+              setFormData({ ...formData, email: e.target.value })
+            }
+            required
+          />
+          <Input
+            label="Password"
+            type="password"
+            value={formData.password}
+            onChange={(e) =>
+              setFormData({ ...formData, password: e.target.value })
+            }
+            required
+          />
+          {error && <div className="error">{error}</div>}
+          <Button type="submit" loading={isLoading}>
+            Login
+          </Button>
+        </form>
+      </div>
+    </div>
+  );
+}
+
+export default withPublic(LoginPage);

package/templates/app/page.jsx

@@ -0,0 +1,10 @@
+/**
+ * Home Page
+ * Responsibility: Landing page with redirect to dashboard
+ */
+
+import { redirect } from "next/navigation";
+
+export default function Home() {
+  redirect("/dashboard");
+}

package/templates/components/auth/withAuth.jsx

@@ -0,0 +1,50 @@
+/**
+ * Protected Route HOC (Redux Version)
+ * Responsibility: Restrict access to authenticated users only
+ *
+ * USAGE GUIDE:
+ * - Wrap any component that requires authentication
+ * - Automatically redirects to login if user is not authenticated
+ *
+ * EXAMPLE:
+ * ```jsx
+ * import { withAuth } from '@/components/auth/withAuth';
+ *
+ * function DashboardPage() {
+ *   return <div>Protected Dashboard</div>;
+ * }
+ *
+ * export default withAuth(DashboardPage);
+ * ```
+ */
+
+"use client";
+
+import { useEffect } from "react";
+import { useRouter } from "next/navigation";
+import { useSelector } from "react-redux";
+import { selectIsAuthenticated, selectToken } from "@/store/slices/authSlice";
+import Loading from "@/components/ui/Loading";
+
+/**
+ * Higher-order component that protects routes requiring authentication
+ */
+export const withAuth = (Component) => {
+  return function ProtectedRoute(props) {
+    const router = useRouter();
+    const isAuthenticated = useSelector(selectIsAuthenticated);
+    const token = useSelector(selectToken);
+
+    useEffect(() => {
+      if (!isAuthenticated && !token) {
+        router.push("/login");
+      }
+    }, [isAuthenticated, token, router]);
+
+    if (!isAuthenticated || !token) {
+      return <Loading />;
+    }
+
+    return <Component {...props} />;
+  };
+};

package/templates/components/auth/withPublic.jsx

@@ -0,0 +1,50 @@
+/**
+ * Public Route HOC (Redux Version)
+ * Responsibility: Restrict access to non-authenticated users only
+ *
+ * USAGE GUIDE:
+ * - Wrap any component that should only be accessible to non-authenticated users
+ * - Automatically redirects to dashboard if user is authenticated
+ * - Perfect for login, register, forgot password pages
+ *
+ * EXAMPLE:
+ * ```jsx
+ * import { withPublic } from '@/components/auth/withPublic';
+ *
+ * function LoginPage() {
+ *   return <div>Login Form</div>;
+ * }
+ *
+ * export default withPublic(LoginPage);
+ * ```
+ */
+
+"use client";
+
+import { useEffect } from "react";
+import { useRouter } from "next/navigation";
+import { useSelector } from "react-redux";
+import { selectIsAuthenticated } from "@/store/slices/authSlice";
+
+/**
+ * Higher-order component that protects routes for non-authenticated users
+ * Redirects to dashboard if user is already logged in
+ */
+export const withPublic = (Component, redirectTo = "/dashboard") => {
+  return function PublicRoute(props) {
+    const router = useRouter();
+    const isAuthenticated = useSelector(selectIsAuthenticated);
+
+    useEffect(() => {
+      if (isAuthenticated) {
+        router.push(redirectTo);
+      }
+    }, [isAuthenticated, router]);
+
+    if (isAuthenticated) {
+      return null;
+    }
+
+    return <Component {...props} />;
+  };
+};

package/templates/components/layout/Header.jsx

@@ -0,0 +1,29 @@
+/**
+ * Header Component
+ * Responsibility: App header with user menu
+ */
+
+"use client";
+
+import { useAuth } from "@/contexts/AuthContext";
+
+export const Header = () => {
+  const { user, logout } = useAuth();
+
+  return (
+    <header className="app-header">
+      <div className="header-content">
+        <h1 className="app-title">App Name</h1>
+
+        <nav className="header-nav">
+          {user && (
+            <div className="user-menu">
+              <span>{user.email}</span>
+              <button onClick={logout}>Logout</button>
+            </div>
+          )}
+        </nav>
+      </div>
+    </header>
+  );
+};

package/templates/components/layout/Sidebar.jsx

@@ -0,0 +1,35 @@
+/**
+ * Sidebar Component
+ * Responsibility: Navigation sidebar
+ */
+
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+
+export const Sidebar = () => {
+  const pathname = usePathname();
+
+  const navItems = [
+    { path: "/dashboard", label: "Dashboard" },
+    { path: "/users", label: "Users" },
+    // Add more navigation items here
+  ];
+
+  return (
+    <aside className="sidebar">
+      <nav className="sidebar-nav">
+        {navItems.map((item) => (
+          <Link
+            key={item.path}
+            href={item.path}
+            className={`nav-item ${pathname === item.path ? "active" : ""}`}
+          >
+            {item.label}
+          </Link>
+        ))}
+      </nav>
+    </aside>
+  );
+};

package/templates/components/ui/Button.jsx

@@ -0,0 +1,36 @@
+/**
+ * Button Component
+ * Responsibility: Reusable button with consistent styling and variants
+ */
+
+/**
+ * Base button component
+ * @param {string} variant - Button style variant: 'primary', 'secondary', 'danger'
+ * @param {string} size - Button size: 'sm', 'md', 'lg'
+ * @param {boolean} disabled - Disabled state
+ * @param {boolean} loading - Loading state
+ * @param {function} onClick - Click handler
+ */
+export const Button = ({
+  children,
+  variant = "primary",
+  size = "md",
+  disabled = false,
+  loading = false,
+  onClick,
+  type = "button",
+  className = "",
+  ...props
+}) => {
+  return (
+    <button
+      type={type}
+      onClick={onClick}
+      disabled={disabled || loading}
+      className={`btn btn-${variant} btn-${size} ${className}`}
+      {...props}
+    >
+      {loading ? "Loading..." : children}
+    </button>
+  );
+};