create-next-structure 1.0.0

package/templates/components/ui/ErrorDisplay.jsx

@@ -0,0 +1,19 @@
+/**
+ * Error Component
+ * Responsibility: Display error state with retry option
+ */
+
+import { Button } from "./Button";
+
+/**
+ * Error display component
+ */
+export const ErrorDisplay = ({ error, onRetry }) => {
+  return (
+    <div className="error-container">
+      <h3>Something went wrong</h3>
+      <p>{error || "An unexpected error occurred"}</p>
+      {onRetry && <Button onClick={onRetry}>Try Again</Button>}
+    </div>
+  );
+};

package/templates/components/ui/Input.jsx

@@ -0,0 +1,30 @@
+/**
+ * Input Component
+ * Responsibility: Reusable form input with validation display
+ */
+
+/**
+ * Base input component
+ * @param {string} label - Input label
+ * @param {string} error - Error message
+ * @param {string} type - Input type
+ */
+export const Input = ({
+  label,
+  error,
+  type = "text",
+  className = "",
+  ...props
+}) => {
+  return (
+    <div className={`input-wrapper ${className}`}>
+      {label && <label className="input-label">{label}</label>}
+      <input
+        type={type}
+        className={`input ${error ? "input-error" : ""}`}
+        {...props}
+      />
+      {error && <span className="error-message">{error}</span>}
+    </div>
+  );
+};

package/templates/components/ui/Loading.jsx

@@ -0,0 +1,16 @@
+/**
+ * Loading Component
+ * Responsibility: Display loading state
+ */
+
+/**
+ * Loading spinner component
+ */
+export const Loading = ({ message = "Loading..." }) => {
+  return (
+    <div className="loading-container">
+      <div className="spinner"></div>
+      <p>{message}</p>
+    </div>
+  );
+};

package/templates/components/ui/Modal.jsx

@@ -0,0 +1,33 @@
+/**
+ * Modal Component
+ * Responsibility: Reusable modal/dialog wrapper
+ */
+
+"use client";
+
+/**
+ * Base modal component
+ * @param {boolean} isOpen - Modal visibility
+ * @param {function} onClose - Close handler
+ * @param {string} title - Modal title
+ */
+export const Modal = ({ isOpen, onClose, title, children, className = "" }) => {
+  if (!isOpen) return null;
+
+  return (
+    <div className="modal-overlay" onClick={onClose}>
+      <div
+        className={`modal-content ${className}`}
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="modal-header">
+          <h2>{title}</h2>
+          <button onClick={onClose} className="modal-close">
+            ×
+          </button>
+        </div>
+        <div className="modal-body">{children}</div>
+      </div>
+    </div>
+  );
+};

package/templates/components/ui/index.js

@@ -0,0 +1,10 @@
+/**
+ * UI Components Export
+ * Responsibility: Centralized export for UI primitives
+ */
+
+export { Button } from "./Button";
+export { Input } from "./Input";
+export { Modal } from "./Modal";
+export { Loading } from "./Loading";
+export { ErrorDisplay } from "./ErrorDisplay";

package/templates/contexts/AuthContext.jsx

@@ -0,0 +1,112 @@
+/**
+ * Auth Context
+ * Responsibility: Manage authentication state and provide auth methods
+ */
+
+"use client";
+
+import { createContext, useContext, useState, useEffect } from "react";
+import { useRouter } from "next/navigation";
+import { authApi } from "@/lib/api/auth.api";
+
+const AuthContext = createContext(null);
+
+export const useAuth = () => {
+  const context = useContext(AuthContext);
+  if (!context) {
+    throw new Error("useAuth must be used within AuthProvider");
+  }
+  return context;
+};
+
+export const AuthProvider = ({ children }) => {
+  const router = useRouter();
+  const [user, setUser] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  /**
+   * Initialize auth state from token
+   */
+  useEffect(() => {
+    const initAuth = async () => {
+      const token = localStorage.getItem("token");
+      if (token) {
+        try {
+          const response = await authApi.getCurrentUser();
+          setUser(response.data);
+        } catch (err) {
+          localStorage.removeItem("token");
+        }
+      }
+      setLoading(false);
+    };
+
+    initAuth();
+  }, []);
+
+  /**
+   * Login user
+   */
+  const login = async (credentials) => {
+    try {
+      setError(null);
+      const response = await authApi.login(credentials);
+      const { token, user: userData } = response.data;
+
+      localStorage.setItem("token", token);
+      setUser(userData);
+
+      return userData;
+    } catch (err) {
+      setError(err.message);
+      throw err;
+    }
+  };
+
+  /**
+   * Register user
+   */
+  const register = async (userData) => {
+    try {
+      setError(null);
+      const response = await authApi.register(userData);
+      const { token, user: newUser } = response.data;
+
+      localStorage.setItem("token", token);
+      setUser(newUser);
+
+      return newUser;
+    } catch (err) {
+      setError(err.message);
+      throw err;
+    }
+  };
+
+  /**
+   * Logout user
+   */
+  const logout = async () => {
+    try {
+      await authApi.logout();
+    } catch (err) {
+      console.error("Logout error:", err);
+    } finally {
+      localStorage.removeItem("token");
+      setUser(null);
+      router.push("/login");
+    }
+  };
+
+  const value = {
+    user,
+    loading,
+    error,
+    login,
+    register,
+    logout,
+    isAuthenticated: !!user,
+  };
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+};

package/templates/docs/README.md

@@ -0,0 +1,128 @@
+# Template Guide (Docs)
+
+This document explains how to use the **Next.js + Redux template** in the `templates/` folder. It focuses only on the template files and how to work with them.
+
+## ✅ What this template includes
+
+- Next.js App Router setup (`app/`)
+- Redux Toolkit + RTK Query (`store/`)
+- Auth helpers (`components/auth/` + `hooks/useAuth.js`)
+- Layout shell (`components/layout/`)
+- Reusable UI primitives (`components/ui/`)
+- Docs for API integration, architecture, and examples (`docs/`)
+
+## 🚀 How to use the template
+
+### 1) Copy or scaffold the template
+
+- Use this folder as your project base, or copy its contents into a fresh Next.js project.
+- The template already has `package.json`, `next.config.js`, and `jsconfig.json`.
+
+### 2) Install dependencies
+
+Use the `package.json` that lives inside `templates/`.
+
+### 3) Configure environment variables
+
+1. Copy `.env.template` into `.env.local`.
+2. Update the API base URL to your backend:
+
+```
+NEXT_PUBLIC_API_URL=http://localhost:5000/api/v1
+```
+
+### 4) Start building pages
+
+- Public pages go under `app/` (ex: `app/page.jsx`).
+- Protected pages should live inside the `(dashboard)` route group and be wrapped by `withAuth`.
+
+## 🔧 How it works (high level)
+
+- **Redux Provider** is mounted in `app/layout.jsx` via `store/ReduxProvider.jsx`.
+- **Auth** flows use RTK Query and `authSlice` to manage tokens.
+- **API calls** are handled by `store/api/apiSlice.js` with automatic token refresh.
+- **Protected routing** uses `components/auth/withAuth.jsx` and `components/auth/withPublic.jsx`.
+
+For deeper guides, see:
+- `docs/API_INTEGRATION.md`
+- `docs/ARCHITECTURE.md`
+- `docs/EXAMPLES.md`
+- `docs/PROJECT_STRUCTURE.md`
+
+## 📁 Template folder structure
+
+```
+templates/
+├── app/
+│   ├── layout.jsx
+│   ├── page.jsx
+│   ├── globals.css
+│   ├── login/
+│   │   └── page.jsx
+│   └── (dashboard)/
+│       ├── layout.jsx
+│       ├── dashboard/
+│       │   └── page.jsx
+│       └── users/
+│           └── page.jsx
+├── components/
+│   ├── auth/
+│   │   ├── withAuth.jsx
+│   │   └── withPublic.jsx
+│   ├── layout/
+│   │   ├── Header.jsx
+│   │   └── Sidebar.jsx
+│   └── ui/
+│       ├── Button.jsx
+│       ├── ErrorDisplay.jsx
+│       ├── Input.jsx
+│       ├── Loading.jsx
+│       ├── Modal.jsx
+│       └── index.js
+├── contexts/
+│   └── AuthContext.jsx
+├── docs/
+│   ├── API_INTEGRATION.md
+│   ├── ARCHITECTURE.md
+│   ├── EXAMPLES.md
+│   ├── PROJECT_STRUCTURE.md
+│   └── README.md
+├── hooks/
+│   ├── useAsync.js
+│   ├── useAuth.js
+│   └── useForm.js
+├── lib/
+│   └── api/
+│       ├── apiClient.js
+│       ├── auth.api.js
+│       └── user.api.js
+├── store/
+│   ├── api/
+│   │   ├── apiSlice.js
+│   │   ├── authApi.js
+│   │   ├── exampleApi.js
+│   │   └── userApi.js
+│   ├── slices/
+│   │   └── authSlice.js
+│   ├── ReduxProvider.jsx
+│   └── store.js
+├── .env.template
+├── jsconfig.json
+├── next.config.js
+└── package.json
+```
+
+## 🧩 Common customization points
+
+- **API base URL** → `store/api/apiSlice.js`
+- **Auth payload shape** → `store/api/authApi.js`
+- **App layout UI** → `components/layout/`
+- **Route protection** → `components/auth/withAuth.jsx`
+- **New RTK Query resources** → copy `store/api/exampleApi.js`
+
+## ✅ Quick sanity checklist
+
+- `.env.local` exists and has `NEXT_PUBLIC_API_URL`
+- `app/layout.jsx` wraps the app in `ReduxProvider`
+- Protected pages use `withAuth`
+- You reference APIs via RTK Query hooks (not manual fetch)

package/templates/hooks/useAsync.js

@@ -0,0 +1,38 @@
+/**
+ * Custom Hook: useAsync
+ * Responsibility: Handle async operations with loading and error states
+ */
+
+"use client";
+
+import { useState, useCallback } from "react";
+
+export const useAsync = () => {
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const [data, setData] = useState(null);
+
+  const execute = useCallback(async (asyncFunction) => {
+    setLoading(true);
+    setError(null);
+
+    try {
+      const result = await asyncFunction();
+      setData(result);
+      return result;
+    } catch (err) {
+      setError(err.message);
+      throw err;
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  const reset = useCallback(() => {
+    setLoading(false);
+    setError(null);
+    setData(null);
+  }, []);
+
+  return { loading, error, data, execute, reset };
+};

package/templates/hooks/useAuth.js

@@ -0,0 +1,93 @@
+/**
+ * Custom Hook: useAuth
+ * Responsibility: Provide authentication state and methods
+ *
+ * USAGE GUIDE:
+ * - Import: import { useAuth } from '@/hooks/useAuth'
+ * - In component: const { user, isAuthenticated, login, logout, register } = useAuth()
+ *
+ * EXAMPLE:
+ * ```jsx
+ * const { user, isAuthenticated, login, logout, isLoading } = useAuth();
+ *
+ * const handleLogin = async (credentials) => {
+ *   try {
+ *     await login(credentials);
+ *     // Success - automatically redirects
+ *   } catch (error) {
+ *     console.error('Login failed:', error);
+ *   }
+ * };
+ * ```
+ */
+
+"use client";
+
+import { useSelector, useDispatch } from "react-redux";
+import { useRouter } from "next/navigation";
+import {
+  selectCurrentUser,
+  selectIsAuthenticated,
+  selectToken,
+  logout as logoutAction,
+} from "@/store/slices/authSlice";
+import {
+  useLoginMutation,
+  useRegisterMutation,
+  useLogoutMutation,
+} from "@/store/api/authApi";
+
+export const useAuth = () => {
+  const dispatch = useDispatch();
+  const router = useRouter();
+
+  const user = useSelector(selectCurrentUser);
+  const isAuthenticated = useSelector(selectIsAuthenticated);
+  const token = useSelector(selectToken);
+
+  const [loginMutation, { isLoading: isLoggingIn }] = useLoginMutation();
+  const [registerMutation, { isLoading: isRegistering }] =
+    useRegisterMutation();
+  const [logoutMutation, { isLoading: isLoggingOut }] = useLogoutMutation();
+
+  const login = async (credentials) => {
+    try {
+      const result = await loginMutation(credentials).unwrap();
+      router.push("/dashboard");
+      return result;
+    } catch (error) {
+      throw error;
+    }
+  };
+
+  const register = async (userData) => {
+    try {
+      const result = await registerMutation(userData).unwrap();
+      router.push("/dashboard");
+      return result;
+    } catch (error) {
+      throw error;
+    }
+  };
+
+  const logout = async () => {
+    try {
+      await logoutMutation().unwrap();
+    } catch (error) {
+      console.error("Logout error:", error);
+    } finally {
+      dispatch(logoutAction());
+      router.push("/login");
+    }
+  };
+
+  return {
+    user,
+    isAuthenticated,
+    token,
+    login,
+    register,
+    logout,
+    isLoading: isLoggingIn || isRegistering || isLoggingOut,
+  };
+};

package/templates/hooks/useForm.js

@@ -0,0 +1,67 @@
+/**
+ * Custom Hook: useForm
+ * Responsibility: Handle form state and validation
+ */
+
+"use client";
+
+import { useState } from "react";
+
+export const useForm = (initialValues = {}, validate) => {
+  const [values, setValues] = useState(initialValues);
+  const [errors, setErrors] = useState({});
+  const [touched, setTouched] = useState({});
+
+  const handleChange = (e) => {
+    const { name, value } = e.target;
+    setValues((prev) => ({ ...prev, [name]: value }));
+
+    // Clear error when user starts typing
+    if (errors[name]) {
+      setErrors((prev) => ({ ...prev, [name]: "" }));
+    }
+  };
+
+  const handleBlur = (e) => {
+    const { name } = e.target;
+    setTouched((prev) => ({ ...prev, [name]: true }));
+
+    // Validate on blur if validation function provided
+    if (validate) {
+      const validationErrors = validate(values);
+      setErrors(validationErrors);
+    }
+  };
+
+  const handleSubmit = (onSubmit) => async (e) => {
+    e.preventDefault();
+
+    // Validate all fields
+    if (validate) {
+      const validationErrors = validate(values);
+      setErrors(validationErrors);
+
+      if (Object.keys(validationErrors).length > 0) {
+        return;
+      }
+    }
+
+    await onSubmit(values);
+  };
+
+  const reset = () => {
+    setValues(initialValues);
+    setErrors({});
+    setTouched({});
+  };
+
+  return {
+    values,
+    errors,
+    touched,
+    handleChange,
+    handleBlur,
+    handleSubmit,
+    reset,
+  };
+};

package/templates/jsconfig.json

@@ -0,0 +1,27 @@
+{
+  "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": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/templates/lib/api/apiClient.js

@@ -0,0 +1,105 @@
+/**
+ * API Client Configuration
+ * Responsibility: Centralized HTTP client with interceptors for Next.js
+ */
+
+const API_BASE_URL =
+  process.env.NEXT_PUBLIC_API_URL || "http://localhost:5000/api/v1";
+
+class ApiClient {
+  constructor(baseURL = API_BASE_URL) {
+    this.baseURL = baseURL;
+  }
+
+  /**
+   * Get auth token from storage (client-side only)
+   */
+  getToken() {
+    if (typeof window !== "undefined") {
+      return localStorage.getItem("token");
+    }
+    return null;
+  }
+
+  /**
+   * Build headers with auth token
+   */
+  getHeaders() {
+    const headers = {
+      "Content-Type": "application/json",
+    };
+
+    const token = this.getToken();
+    if (token) {
+      headers["Authorization"] = `Bearer ${token}`;
+    }
+
+    return headers;
+  }
+
+  /**
+   * Generic request handler
+   */
+  async request(endpoint, options = {}) {
+    const url = `${this.baseURL}${endpoint}`;
+    const config = {
+      ...options,
+      headers: {
+        ...this.getHeaders(),
+        ...options.headers,
+      },
+    };
+
+    try {
+      const response = await fetch(url, config);
+      const data = await response.json();
+
+      if (!response.ok) {
+        throw new Error(data.message || "Something went wrong");
+      }
+
+      return data;
+    } catch (error) {
+      console.error("API Error:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * GET request
+   */
+  async get(endpoint, params = {}) {
+    const queryString = new URLSearchParams(params).toString();
+    const url = queryString ? `${endpoint}?${queryString}` : endpoint;
+    return this.request(url, { method: "GET" });
+  }
+
+  /**
+   * POST request
+   */
+  async post(endpoint, body) {
+    return this.request(endpoint, {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * PUT request
+   */
+  async put(endpoint, body) {
+    return this.request(endpoint, {
+      method: "PUT",
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * DELETE request
+   */
+  async delete(endpoint) {
+    return this.request(endpoint, { method: "DELETE" });
+  }
+}
+
+export default new ApiClient();