This is NOT the next.js you know

This version has breaking changes - APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.

Idea Guru Template

Next.js 16 (App Router) starter template with Typescript, Tailwind CSS v4, and shadcn/ui (base-nova style).

Commands

pnpm dev - Start the development server
pnpm build - Build the application for production
pnpm start - Start the production server
pnpm lint - Run ESLint to check for code issues

Prejct Structure

src/app/ - Next.js App Router pages and layouts
src/components/ui/ - shadcn/ui components (managed by pnpm dlx shadcn@latest add <component-name>)
src/components/layouts/ - layout components (Header, Footer, etc.)
src/components/common/ - reuseable app-level components
src/hooks/ - custom React hooks
src/lib/ - utility modules (axios, query-client, validations, env, utils)
src/providers/ - React context providers (AuthProvider, ThemeProvider, QueryClientProvider, etc.)
src/stores/ - Zustand stores for global state management
src/types/ - TypeScript type definitions and interfaces

Dependencies

Do NOT install new dependencies. Use only the libraries already in the package.json. Adding shadcn/ui components via pnpm dlx shadcn-ui add <component-name> is allowed since it generates code, not new dependencies.

Conventions

Package manager: pnpm (never use npm or yarn)
Imports: always use the @/* path alias (maps to src/*)
Styling: Tailwind CSS utility classes; avoid custom CSS. Usecn() from @/lib/utils fro conditional classes
Components: use shadcn/ui as the base component library. shadcn uses @base-ui/react (not Radix) and does NOT support asChild - use buttonVariant() with cn() for link-styled buttons instead.
State: Zustand for client-side global state; TanStack Query for server/async state
Theme: use next-themes (useTheme()) for dark mode support. Do NOT manage theme in Zustand or any other global state.
Data fetching: wrap Axios calls in TanStack Query hooks (see src/hooks/use-example-query.ts)
Forms: React Hook Form + Zod Schemas from @/lib/validations.ts
Animation: Framer Motion
Icons: Lucide React
Dates: date-fns
Authentication: Auth.js (next-auth) for authentication flows
Internationalization: next-intl for handling translations and locale-specific content
Error Monitoring: Sentry (@sentry/nextjs) for error tracking and performance monitoring
Toasts: Sonner (not the deprecated shadcn toast)
ESLint: flat config (eslint.config.mjs) with next/core-web-vitals, next/typescript, and prettier
Prettier: configred in .prettierrc with prettier-plugin-tailwindcss

Key Files

src/lib/axios.ts - Axios instance with interceptors for auth tokens and error handling
src/lib/query-client.ts - TanStack Query client configuration
src/lib/env.ts - Zod-validated environment variables (client + server)
src/providers/index.tsx - app-wide providers (wrap children in layout.tsx)
src/stores/use-app-store.ts - Zustand store with persist middlerware
.env.example - template for environment variables

Important Notes

Although the server-side dependencies are included in package.json, this template is primarily focused on client-side development. Do NOT add any server-side code or API routes. The server-side dependencies are included for potential future use but are not intended to be used in this template.
If there are any features that current dependencies cannot support, try to implement them within the constraints of the existing libraries. For example, if you need to implement authentication flows, use next-auth and do not add any new authentication libraries.
If the feature is impossible to implement with the current dependencies, you can refuse the request and explain the limitations. However, try to find creative solutions within the existing tools before refusing any requests.
All new files and directories must be created within the src/ or public/ directories and follow the established structure and conventions. Do NOT create any files or directories outside of these locations. This is to maintain a clean and organized project structure.
Do NOT modify configuration files such as package.json, next.config.js, eslint.config.mjs, prettier.config.mjs, or tsconfig.json.

4.5 KiB Raw Permalink Blame History