ntc-dev-kit 1.0.0__py3-none-any.whl

ntc/templates/nextjs/knowledge/knowledge_design_pattern.md

@@ -0,0 +1,460 @@
+# Design Patterns and Coding Conventions - {project_name}
+
+This document describes the design patterns and coding conventions used in this NTC-generated Next.js project.
+
+## 🎨 Component Design Patterns
+
+### Server Component Pattern
+```typescript
+// Default: Server Component (no 'use client' directive)
+interface ComponentProps {
+  title: string
+}
+
+const Component = ({ title }: ComponentProps) => {
+  // Server-side logic
+  return <div>{title}</div>
+}
+
+export default Component
+```
+
+### Client Component Pattern
+```typescript
+'use client'
+
+import { useState } from 'react'
+
+interface ComponentProps {
+  title: string
+  onAction: () => void
+}
+
+const Component = ({ title, onAction }: ComponentProps) => {
+  const [count, setCount] = useState(0)
+  
+  return <div>{title}</div>
+}
+
+export default Component
+```
+
+### Custom Hook Pattern
+```typescript
+'use client'
+
+const useCustomHook = (param: string) => {
+  const [state, setState] = useState<string>('')
+
+  useEffect(() => {
+    // Effect logic
+  }, [param])
+
+  return state
+}
+```
+
+## 🔧 Service Layer Pattern
+
+### API Service Pattern
+```typescript
+const apiService = {
+  get: (url: string, config = {}) => apiClient.get(url, config),
+  post: (url: string, data = {}, config = {}) => apiClient.post(url, data, config),
+  // ... other methods
+}
+```
+
+### Auth Service Pattern
+```typescript
+export const authService = {
+  login: async (credentials: LoginCredentials) => {
+    const response = await apiService.post('/auth/login/', credentials)
+    if (response.data.token) {
+      localStorage.setItem('authToken', response.data.token)
+    }
+    return response
+  },
+  logout: () => {
+    localStorage.removeItem('authToken')
+  },
+  // ... other methods
+}
+```
+
+## 📝 TypeScript Patterns
+
+### Interface for Props
+```typescript
+interface ButtonProps {
+  label: string
+  onClick: () => void
+  disabled?: boolean
+}
+
+const Button = ({ label, onClick, disabled = false }: ButtonProps) => {
+  return <button onClick={onClick} disabled={disabled}>{label}</button>
+}
+```
+
+### Type Guards
+```typescript
+const isString = (value: unknown): value is string => {
+  return typeof value === 'string'
+}
+
+const processValue = (value: unknown) => {
+  if (isString(value)) {
+    return value.toUpperCase()
+  }
+  return 'DEFAULT'
+}
+```
+
+### Generic Types
+```typescript
+interface ApiResponse<T> {
+  data: T
+  status: number
+  message: string
+}
+
+const fetchData = async <T>(url: string): Promise<ApiResponse<T>> => {
+  const response = await apiService.get<ApiResponse<T>>(url)
+  return response.data
+}
+```
+
+## 🎯 State Management Patterns
+
+### Server Component State
+```typescript
+// Server Components can fetch data directly
+const Component = async ({ id }: { id: string }) => {
+  const data = await fetchData(id)
+  
+  return <div>{data.name}</div>
+}
+```
+
+### Client Component State
+```typescript
+'use client'
+
+const Component = () => {
+  const [count, setCount] = useState(0)
+  const [loading, setLoading] = useState(false)
+  
+  const increment = () => setCount(prev => prev + 1)
+  
+  return <div>{count}</div>
+}
+```
+
+### Context Pattern (Client Only)
+```typescript
+'use client'
+
+interface AppContextType {
+  user: User | null
+  setUser: (user: User | null) => void
+}
+
+const AppContext = createContext<AppContextType | undefined>(undefined)
+
+export const AppProvider = ({ children }: { children: React.ReactNode }) => {
+  const [user, setUser] = useState<User | null>(null)
+  
+  return (
+    <AppContext.Provider value={{ user, setUser }}>
+      {children}
+    </AppContext.Provider>
+  )
+}
+
+export const useApp = () => {
+  const context = useContext(AppContext)
+  if (!context) {
+    throw new Error('useApp must be used within AppProvider')
+  }
+  return context
+}
+```
+
+## 🔄 Async Pattern
+
+### Server Component Async
+```typescript
+const Component = async () => {
+  const data = await fetchData()
+  
+  return <div>{data.name}</div>
+}
+```
+
+### Client Component Async
+```typescript
+'use client'
+
+const Component = () => {
+  const [data, setData] = useState<Data | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [loading, setLoading] = useState(false)
+
+  const fetchData = async () => {
+    setLoading(true)
+    setError(null)
+    try {
+      const response = await apiService.get('/endpoint')
+      setData(response.data)
+    } catch (err) {
+      setError('Failed to fetch data')
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  useEffect(() => {
+    fetchData()
+  }, [])
+
+  if (loading) return <Loading />
+  if (error) return <Error message={error} />
+  
+  return <div>{data?.name}</div>
+}
+```
+
+## 🎨 Layout Pattern
+
+### Root Layout Pattern
+```typescript
+export const metadata: Metadata = {
+  title: '{project_name}',
+  description: 'A modern website built with Next.js',
+}
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+### Nested Layout Pattern
+```typescript
+export default function DashboardLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <div className="dashboard">
+      <Sidebar />
+      <main>{children}</main>
+    </div>
+  )
+}
+```
+
+## 🎨 SEO Pattern
+
+### Metadata API Pattern
+```typescript
+import { Metadata } from 'next'
+
+export const metadata: Metadata = {
+  title: 'Page Title',
+  description: 'Page description',
+  keywords: ['keyword1', 'keyword2'],
+  openGraph: {
+    title: 'Page Title',
+    description: 'Page description',
+    type: 'website',
+  },
+}
+```
+
+### Dynamic Metadata Pattern
+```typescript
+export async function generateMetadata({ params }: { params: { id: string } }): Promise<Metadata> {
+  const data = await fetchData(params.id)
+  
+  return {
+    title: data.name,
+    description: data.description,
+  }
+}
+```
+
+## 📦 File Organization Patterns
+
+### App Router Structure
+```
+src/app/
+├── layout.tsx        # Root layout
+├── page.tsx          # Home page
+├── about/
+│   ├── page.tsx      # About page
+│   └── layout.tsx    # About layout
+├── blog/
+│   ├── page.tsx      # Blog listing
+│   ├── [slug]/
+│   │   └── page.tsx  # Blog post
+│   └── layout.tsx    # Blog layout
+└── api/              # API routes
+    └── route.ts
+```
+
+### Type-Based Structure
+```
+src/
+├── app/              # App Router pages and layouts
+├── components/       # Reusable components
+├── services/         # API services
+├── hooks/            # Custom hooks
+├── types/            # TypeScript types
+├── utils/            # Utility functions
+└── lib/              # Third-party library configurations
+```
+
+## 🔒 Error Handling Patterns
+
+### Error Boundary Pattern
+```typescript
+'use client'
+
+class ErrorBoundary extends React.Component<{ children: React.ReactNode }, { hasError: boolean }> {
+  constructor(props: { children: React.ReactNode }) {
+    super(props)
+    this.state = { hasError: false }
+  }
+
+  static getDerivedStateFromError() {
+    return { hasError: true }
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return <div>Something went wrong</div>
+    }
+    return this.props.children
+  }
+}
+```
+
+### Try-Catch in Async Operations
+```typescript
+const safeAsyncOperation = async () => {
+  try {
+    const result = await apiService.get('/endpoint')
+    return result
+  } catch (error) {
+    console.error('Operation failed:', error)
+    throw error
+  }
+}
+```
+
+## 🚀 Performance Patterns
+
+### Dynamic Import Pattern
+```typescript
+const DynamicComponent = dynamic(() => import('./Component'), {
+  loading: () => <Loading />,
+  ssr: false,
+})
+```
+
+### Image Optimization Pattern
+```typescript
+import Image from 'next/image'
+
+<Image
+  src="/image.jpg"
+  alt="Description"
+  width={500}
+  height={300}
+  priority
+/>
+```
+
+### Font Optimization Pattern
+```typescript
+import { Inter } from 'next/font/google'
+
+const inter = Inter({ subsets: ['latin'] })
+```
+
+## 📐 Naming Conventions
+
+### Components
+- **File**: `PascalCase.tsx` (e.g., `UserProfile.tsx`)
+- **Component**: `PascalCase` (e.g., `UserProfile`)
+- **Props Interface**: `ComponentProps` (e.g., `UserProfileProps`)
+
+### Pages
+- **File**: `page.tsx` (Next.js convention)
+- **Layout**: `layout.tsx` (Next.js convention)
+- **Route**: File-based routing
+
+### Hooks
+- **File**: `camelCase.ts` (e.g., `useUserProfile.ts`)
+- **Hook**: `camelCase` starting with `use` (e.g., `useUserProfile`)
+
+### Services
+- **File**: `camelCase.ts` (e.g., `apiService.ts`)
+- **Service**: `camelCase` (e.g., `apiService`)
+
+### Types
+- **File**: `PascalCase.types.ts` (e.g., `User.types.ts`)
+- **Interface**: `PascalCase` (e.g., `UserProfile`)
+- **Type**: `PascalCase` (e.g., `ApiResponse`)
+
+### Constants
+- **File**: `camelCase.ts` (e.g., `constants.ts`)
+- **Constant**: `UPPER_SNAKE_CASE` (e.g., `API_BASE_URL`)
+
+## 🎯 Best Practices
+
+### Code Organization
+1. Keep components small and focused
+2. Extract reusable logic into custom hooks
+3. Use TypeScript interfaces for all props
+4. Organize imports (external, internal, types)
+5. Use path aliases (`@/`) for internal imports
+
+### Performance
+1. Use Server Components by default
+2. Use Client Components only when needed
+3. Implement code splitting with dynamic imports
+4. Optimize images with Next.js Image component
+5. Use streaming for large pages
+
+### SEO
+1. Use Metadata API for all pages
+2. Implement proper meta tags
+3. Use semantic HTML elements
+4. Add structured data (JSON-LD)
+5. Optimize page load times
+6. Ensure mobile responsiveness
+
+### Accessibility
+1. Use semantic HTML elements
+2. Provide alt text for images
+3. Ensure keyboard navigation
+4. Use ARIA labels where needed
+5. Test with screen readers
+
+### Security
+1. Sanitize user input
+2. Use HTTPS in production
+3. Validate data on client and server
+4. Never expose sensitive data
+5. Use environment variables for secrets

ntc/templates/nextjs/knowledge/knowledge_structure.md

@@ -0,0 +1,75 @@
+# Project Structure - {project_name}
+
+This document describes the complete project structure and organization for AI assistants to understand how to work with this codebase.
+
+## 📁 Root Directory Structure
+
+```
+{project_name}/
+├── .env.example           # Environment variables example
+├── .gitignore            # Git ignore patterns
+├── .knowledge/           # AI documentation (this directory)
+├── package.json          # Node.js dependencies
+├── tsconfig.json         # TypeScript configuration
+├── next.config.js        # Next.js configuration
+├── README.md             # Project documentation
+└── src/                  # Source code
+```
+
+## 🏗️ Source Directory Structure (`src/`)
+
+```
+src/
+├── app/                  # Next.js App Router
+│   ├── layout.tsx        # Root layout with SEO metadata
+│   ├── page.tsx          # Home page
+│   └── globals.css       # Global styles
+├── components/           # Reusable UI components
+│   └── Header.tsx        # Header component
+├── services/             # API and external services
+│   └── api.ts            # API service with axios
+└── utils/                # Utility functions
+    └── constants.ts      # Constants and configuration
+```
+
+## 🎯 Key Conventions
+
+### File Naming
+- **Components**: `PascalCase` with `.tsx` extension (e.g., `UserProfile.tsx`)
+- **Pages**: `PascalCase` with `.tsx` extension (e.g., `AboutPage.tsx`)
+- **Services**: `camelCase` with `.ts` extension (e.g., `api.ts`)
+- **Utils**: `camelCase` with `.ts` extension (e.g., `formatDate.ts`)
+- **Types**: `PascalCase` with `.ts` extension (e.g., `UserTypes.ts`)
+
+### Import Patterns
+- **Components**: `import Component from '@/components/Component'`
+- **Services**: `import { apiService } from '@/services/api'`
+- **Utils**: `import { CONSTANT } from '@/utils/constants'`
+- **Types**: `import { UserType } from '@/types'`
+
+### TypeScript Patterns
+- **Props Interface**: Always define interfaces for component props
+- **Generic Types**: Use generics when appropriate for reusable components
+- **Strict Mode**: TypeScript strict mode is enabled
+- **No Any**: Avoid using `any` type, use `unknown` or proper types instead
+
+## 🔄 Development Workflow
+
+1. **Install dependencies**: `npm install`
+2. **Run development server**: `npm run dev`
+3. **Build for production**: `npm run build`
+4. **Start production server**: `npm start`
+5. **Run linter**: `npm run lint`
+
+## 📋 Important Notes for AI
+
+- **Always use TypeScript** with proper type definitions
+- **Follow the component structure** when creating new components
+- **Use the apiService** for all API calls
+- **Handle loading and error states** in async operations
+- **Use environment variables** via `process.env.NEXT_PUBLIC_*`
+- **Path aliases**: Use `@` for `src/` directory imports
+- **Next.js App Router**: This project uses the App Router (not Pages Router)
+- **Port**: Development server runs on http://localhost:3000
+- **SEO**: Use Next.js Metadata API for SEO optimization
+- **Server Components**: Use Server Components by default, use Client Components when needed