Awesome Cursor Rules Collection

# Cursor Rules

Assume the role of a Golang programmer using [Encore framework](https://encore.dev/docs/go).

- The project will follow uses domain driven design and hexagonal architecture.

## Folder structure for example module using domain driven design and hexagonal architecture

```
alarms
├── application
│   ├── commands
│   │   ├── create_alarm_command_handler.go
│   │   └── create_alarm_command.go
│   ├── events
│   │   └── alarm_created_event_handler.go
│   ├── queries
│   │   ├── list_alarms_query.go
│   │   └── list_alarms_query_handler.go
│   ├── ports
│   │   ├── create_alarm_repository_port.go
│   │   ├── find_alarms_repository_port.go
│   │   └── upsert_materialized_alarm_repository_port.go
│   └── alarms_facade.go
│   └── alarms_factory.go
├── domain
│   ├── aggregates
│   │   └── alarm_aggregate.go
│   ├── events
│   │   └── alarm_created_event.go
│   ├── models
│   │   └── alarm_read_model.go
│   ├── valueobjects
│   │   └── alarm_severity.go
│   ├── entities
│   │   └── alarm.go
│   │   └── alarm_item.go
├── infrastructure
│   └── persistence
│       ├── entities
│       │   ├── alarm_entity.go
│       │   └── alarm_item_entity.go
│       ├── mappers
│       │   └── alarm_mapper.go
│       ├── repositories
│       │   ├── migrations
│       │   │   └── 1_create_foo_table.sql
│       │   │   └── 2_create_bar_table.sql
│       │   │   └── 3_add_column_x_on_foo_table.sql
│       │   ├── create_alarm_repository.go
│       │   ├── find_alarms_repository.go
│       │   └── upsert_materialized_alarm_repository.go
│       └── schemas
│           └── materialized_alarm_view_schema.go
└── presentation
    └── http
        ├── dto
        │   └── create_alarm_dto.go
        └── alarms_controller.go
```

## Hexagonal Architecture Specifications

### Presentation Layer

- The presentation layer contains user facing-components, such has controllers, gateways and other APIs.
- The presentation layer commands to forward data to application services (e.g., facades).
- The presentation layer queries to forward data to application services (e.g., facades).

### Application Layer

- The applicational layer contains application services (e.g., facades, handlers).
- The applicational exposes primary ports and secondary ports.
- The applicational primary ports include commands and query structs and applicational service interfaces.
- The applicational secondary ports (a.k.a. adapters) are implemented on the infrastructure layer.
- The application layer can access the infrastructure layer via secondary port interfaces.
- The application layer can access the domain layer through aggregates that are exposed by the domain layer.
- The application layer can access the domain layer through domain objects only on simple (e.g., little or no business logic, data-reads).
- The application layer can not access anything from the presentation layer, not even data transfer objects.
- Commands should be concrete classes or structs.
- Commands define payloads that the application layer to uses to start data-write procedures, with or without CQRS implementation.
- Queries should be concrete classes or structs.
- Queries define payloads that the application layer to uses to start data-read procedures, with or without CQRS implementation.
- Applicational services should always expose an abstract class or interfaces.
- Applicational service interfaces will be used in module initialization.
- Secondary ports should always be interfaces.
- Secondary ports are implemented by Adapters at the infrastructure layer (e.g., ICreateAlarmRepository from application layer is implemented in CreateAlarmRepository and/or CreateAlarmRepositoryV2 at infrastructure layer).

### Domain Layer

- The domain layer contains domain models, value objects, events and other domain specific components that represent the business.
- The domain layer can only be accessed from the applicational layer.

### Infrastructure layer

- The infrastructure layer contains data access components, such as message brokers, repositories and clients to external system.
- The infrastructure layer implements the secondary (ports) defined by the application layer called adapters (e.g., concrete repository).
- The infrastructure layer can only be accessed from the applicational layer.
- Adapters use mapper classes to ensure domain or value objects, are returned its methods.
- Adapters can reference domain classes and value objects, but should not operate or modify them.

## Domain Driven Design Specifications (considering Hexagonal Architecture)

### Core Concepts

- Value objects must be immutable and have no identifiers (ID).
- Value objects should be immutable and side-effect free.
- Entities must have unique identifiers (ID) and can be mutable.
- Entities are represented by domain objects on the domain layer.
- Entities are represented by sqlc objects (entity or models) on the infrastructure layer.
- Aggregates are clusters of domain objects treated as single units for consistency.
- Aggregates changes occur in memory and are persisted via together through transactions.
- Domain objects within aggregates can only be changed through aggregates public interface.

### Factories

- Use factories to handle struct validation and initialization logic.
- Use factories to hide implementation details behind complex object creation.
- Use factories to keep domain models focused on business logic

### Services

- Use applicational services (e.g., facades, usecases) to coordinate and fullfil applicational commands and queries.
- Use applicational services to communicate with the infrastructure and domain layers from the application layer.
- Use domain services (aggregates) to coordinate changes across multiple domain objects and/or value-objects.
- Use domain services (root aggregates) for logic that does not belong to a single aggregate.
- Root aggregates and aggregates should only be created when they contain actual business logic, not just getters/setters.
- Avoid creating domain services for any other purpose other than the highlighted ones.

### Repositories

- Repositories should be used to effectuate persisting/retrieving of entity objects.
- Repositories should return domain objects.
- Repositories should use mappers to convert domain objects to entity objects.
- Repositories should use mappers to convert objects objects to domain objects.
- Repositories should convert entity objects to SQLC parameters inline when performing queries.
- Repositories should hide implementation details of the underlying storage (sql, nosql, cache, in-memory).

### Events

- Domain events should represent domain state changes that have been persisted.
- Domain events should be emitted from domain layer.
- Domain events should be declared and handled in application layer.
- Domain events handlers that are declared in the application layer can access infrastructure layer.
- Domain events handlers can be declared and handled in domain layer for ponctual and only for pure business policy reactions.
- Domain events handlers that are declared in the domain layer can not access infrastructure layer.
- Integration events should be for cross-service communication (e.g., separate module boundary).
- Integration events should be lighter than domain events.

### CQRS

- Separate read and write operations
- Write side handles commands and state updates
- Read side handles events and read model updates
- Eventual consistency between read/write models
- Best for read-heavy systems

## Golang Specifications

### Basic Principles

- Always write code and documentation in English.
- Prompt requirements should be followed carefully.
- Prompt requirements should have priority over rules outlined in this document.
- Add logs often and frequently using Encore logger (package: encore.dev/rlog).
- Add logs with debug, info, warn, error and fatal levels as appropriate.
- Add middleware to handle Cross-cutting concerns (e.g., catch-all error handling and logging, authentication, etc.).
- Comments should be added to every exported (public) functions or variables.
- Comments should not be added to unexported (private) functions or variables, unless prompted.
- Consider Encore framework intricacies when writting code.
- Rest endpoints should authentication/authorization as appropriate,
- Rest endpoints should implement basic validation using Encore Validation mechanism.
- Rest endpoints should implement rate limiting as appropriate.
- Rest endpoints should return appropriate status codes.
- Rest endpoints should return json.
- Domain aggregates should implement business concern validations using spec functions inspired by Domain Driven Desing.
- Include necessary imports, package declarations, and any required setup code.
- Inform me when the setup code requires me to install a go or 3rd party package.

### Nomenclature

- Use PascalCase for public variables, functions, interfaces and structs.
- Use camelCase for package private variables, functions, interfaces and structs.
- Use camelCase for block-scoped variables.
- Use UPPERCASE for constant and environment variables.
- Use lowcase for directory names.
- Use snake_case for file names.
- Use snake_case specifiers after the actual file name, before the file extension (e.g., 'settings_controller.go').
- Use verbs such has `is`, `has` and `can` to denote Booleanish variables (e.g., isLoading, hasError, canDelete).
- Use complete words instead of abbreviations. The following exceptions are made:
    - i, j denoting iterated values or indexes in loops
    - args denoting arguments
    - ctx denoting context
    - err denoting error
    - next denoting next middleware
    - params denoting parameters
    - req denoting request
    - res denoting response
    - Db denoting Database
    - Api denoting Access Pointer Interface
    - Url denoting Unique Resource Locator
    - Http denoting Hyper Text Transfer Protocol

### Errors and Exceptions

- Errors should be handled often to fix recoverable problems, log or add context.
- Errors should be bubbled up if we can not do anything useful with them.
- It is okay to use `defer` and `recovery` to handle some `panic` events at the top level of the application.

### Functions Specifics

- Functions should have names that start with a verb (e.g., CreateFlag, DeactivateUser).
- Functions should be short, concise and side-effect free.
- Functions should accept no more than four parameters.
- Functions should accept interfaces when they absolutly need a large quantity of parameters.
- Functions should avoid deeply nested blocks.
- Functions should not validate parameters unless asked as part of prompted requirements.

### Testing

- Test can use official Golang, `go-resty/resty` and `stretchr/testify` packages.
- Test names should be concise.
- Test names should start with a verb. Example: TestReturnsFooBar
- Test names should not contain redudant (implied) verbs such has "should", "must" and "check".
- Tests blocks the Arrange-Act-Assert convention for tests.
- Test variable names should follow the convention: inputX, mockX, actualX, expectedX, etc.
- Unit tests should be written for pure functions that are publicly exposed by modules.
- Unit tests should be written methods of controllers, facades, factories, mappers, services, repositories, etc.
- Unit tests should use mocks, stubs, spies and doubles to simulate dependencies unless prompted otherwise.
- Acceptance (API or E2E) tests should be written for api endpoints or application entry points.

# .cursorrules for Webflow CMS AI Content Creation SaaS

## Project Overview
- SaaS application for AI-powered content creation in Webflow CMS
- Focus on SEO optimization
- Built with Refine Dev, NextJS, Ant Design, and Appwrite

## Tech Stack
- Frontend: NextJS (App Router)
- UI Components: Ant Design
- Backend & Authentication: Appwrite
- Framework: Refine Dev

## Coding Standards
- Use TypeScript for type safety
- Implement ESLint and Prettier for code consistency
- Follow Refine Dev best practices

## File Structure
- Use Next.js App Router structure
- Organize components in a logical hierarchy
- Separate business logic from UI components

## SEO Optimization
- Implement proper metadata for each page
- Use semantic HTML tags
- Optimize images with Next.js Image component

## Ant Design Usage
- Use Ant Design components consistently
- Customize theme using Ant Design's ConfigProvider
- Implement responsive design principles

## Appwrite Integration
- Use Appwrite SDK for authentication and backend operations
- Implement proper error handling for Appwrite API calls
- Secure API keys and sensitive information using environment variables

## AI Integration
- Implement AI-powered content generation features
- Optimize AI-generated content for SEO
- Ensure proper error handling and fallbacks for AI operations

## Performance
- Implement code splitting and lazy loading
- Optimize API calls and data fetching
- Use server-side rendering where appropriate

## Testing
- Write unit tests for critical components and functions
- Implement integration tests for key user flows
- Use Jest and React Testing Library for testing

## Documentation
- Maintain clear and up-to-date documentation
- Document API endpoints and their usage
- Include setup instructions in the README.md file

## Refine Dev Specific
- Utilize Refine hooks and components for data management
- Implement custom hooks for business logic
- Use Refine's auth provider with Appwrite

## Cursor-specific Instructions
- Prioritize server components unless client-side interactivity is required
- Use the `use client` directive for client components
- Implement proper loading and error states using Next.js 13+ conventions

You are an expert in TypeScript, Vite, React and Tailwind.

Code Style and Structure

- Write concise, technical TypeScript code.
- Use functional and declarative programming patterns; avoid classes.
- Prefer iteration and modularization over code duplication.
- Use descriptive variable names with auxiliary verbs (e.g., isLoaded, hasError).
- Structure files: exported page/component, helpers, static content, types.

Naming Conventions

- Favor named exports for components and utilities.

TypeScript Usage

- Use TypeScript for all code; prefer interfaces over types.
- Avoid enums; use objects or maps instead.
- Avoid using `any` or `unknown` unless absolutely necessary. Look for type definitions in the codebase instead.
- Avoid type assertions with `as` or `!`.

Syntax and Formatting

- Use the "function" keyword for pure functions.
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
- Use declarative JSX, keeping JSX minimal and readable.

UI and Styling

- Use Tailwind for utility-based styling

// Solid.js with Tailwind CSS .cursorrules

// Prefer functional components
const preferFunctionalComponents = true;

// Solid.js and Tailwind CSS best practices
const solidjsTailwindBestPractices = [
  "Use createSignal() for reactive state",
  "Implement Tailwind CSS classes for styling",
  "Utilize @apply directive in CSS files for reusable styles",
  "Implement responsive design using Tailwind's responsive classes",
  "Use Tailwind's configuration file for customization",
  "Implement dark mode using Tailwind's dark variant",
];

// Folder structure
const folderStructure = `
src/
  components/
  pages/
  styles/
  App.jsx
  index.jsx
public/
  index.html
tailwind.config.js
postcss.config.js
`;

// Additional instructions
const additionalInstructions = `
1. Use JSX for component templates
2. Implement proper Tailwind CSS purging for production builds
3. Utilize Solid Router for routing when applicable
4. Use Tailwind's @layer directive for custom styles
5. Implement utility-first CSS approach
6. Follow both Solid.js and Tailwind naming conventions
7. Use JIT (Just-In-Time) mode for faster development
`;

# JSON Beautifier Project Rules

## File Structure

- Components should be placed in `components/` directory
- Reusable UI components should be in `components/ui/`
- Utility functions should be in `lib/utils/`
- Hooks should be in `hooks/`
- Types should be in `types/`
- Constants should be in `lib/constants/`

## Naming Conventions

- Components: PascalCase (e.g., JSONInput, JSONFormatter)
- Functions: camelCase
- Files: kebab-case for pages, PascalCase for components
- Constants: UPPER_SNAKE_CASE
- Types/Interfaces: PascalCase with 'T' prefix for types, 'I' for interfaces

## Component Rules

- Each component should have its own directory with:
  - index.tsx (main component)
  - types.ts (component types)
  - styles.module.css (if needed)
  - utils.ts (component-specific utilities)
  - test.tsx (component tests)

## Code Style

- Use TypeScript strict mode
- Use ES6+ features
- Prefer const over let
- Use optional chaining
- Use nullish coalescing
- Use early returns
- Max line length: 100 characters

## Performance Rules

- Use React.memo for expensive computations
- Implement virtualization for large datasets
- Use web workers for heavy computations
- Implement proper error boundaries
- Use proper React hooks dependencies

## State Management

- Use React Context for theme/settings
- Use URL state for sharing
- Use local state for component-specific data
- Implement proper state persistence

## Testing Requirements

- Unit tests for utilities
- Integration tests for components
- E2E tests for critical flows
- Accessibility tests
- Performance tests

## Accessibility Rules

- All interactive elements must be keyboard accessible
- Use proper ARIA labels
- Maintain proper heading hierarchy
- Ensure proper color contrast
- Support screen readers

## Error Handling

- Implement proper error boundaries
- Use toast notifications for user feedback
- Log errors properly
- Provide user-friendly error messages
- Handle edge cases gracefully

## Documentation

- JSDoc for functions and components
- README for each component
- Inline comments for complex logic
- Type documentation
- Usage examples

## Security

- Sanitize JSON input
- Validate user input
- Handle large files safely
- Implement proper CSP
- No sensitive data in logs

## Performance Metrics

- First contentful paint < 1.5s
- Time to interactive < 3.5s
- Lighthouse score > 90
- Bundle size < 200KB (initial load)
- JSON parsing < 100ms for 1MB file

## Dependencies

- Next.js
- TypeScript
- Tailwind CSS
- ShadcN UI
- React
- ESLint
- Prettier
- Jest
- Testing Library
- Cypress

my name is mckay

always add 'use client' at the top of the file if you are using react client side

when generating code, add helpful comments to explain the code because I am a newbie

# 규칙


## 패키지 매니저
- **패키지 매니저** `bun`을 사용합니다.

## UI 컴포넌트 생성
- **ShadCN 컴포넌트를 우선적으로 활용합니다.**
- **ShadCN 컴포넌트 추가 명령어**:
  - CLI 명령어 예시: `bunx shadcn@latest add accordion`

# Next.js Server Actions & API Routes 사용 지침
- 이 지침은 **Next.js** 프로젝트에서 **Server Actions**와 **API Routes**를 어떻게 적절히 사용할지에 대한 안내입니다.

## Next.js Server Actions
- **Next.js Server Actions**는 **간단한 데이터 작업** 또는 **기본 CRUD** 작업에 사용합니다. 이 기능은 컴포넌트 내에서 서버 작업을 직접 처리할 수 있어 추가적인 외부 API 호출이나 다단계 처리가 필요하지 않은 경우에 적합합니다.
- 복잡한 비즈니스 로직이나 외부 API 호출, 또는 다단계 처리가 필요하지 않은 경우에 Server Actions를 사용합니다.
- 예시
  - 사용자별 데이터를 페이지에 로드.
  - 간단한 폼 처리 (예: 새로운 항목 추가, 좋아요 버튼 클릭 처리).

## Next.js API Routes
- **Next.js API Routes**는 **복잡한 비즈니스 로직**이나 **외부 API 통신**, **세션 관리** 등의 작업에 사용합니다.
  - 인중. 권한 관리, 또는 트랜잭션 같은 중요한 작업에서 API Routes를 사용하여 처리 흐름을 더 명확하게 관리할 수 있습니다.
  - 외부 서비스와의 통합이나 다단계 프로세스가 필요한 경우 적합합니다.
- 예시:
  - 결제 처리. 주문 관리, 외부 API 호출 등 복잡한 작업.
  - 사용자 인증 및 권한 관리가 필요한 API 엔드포인트.

## 일반 규칙
- **Next.js** 프로젝트에서 간단한 데이터 처리는 **Server Actions**를 사용하여 성능 최적화와 코드 간결성을 유지합니다.
- 복잡한 로직, 확장성, 또는 외부 API 통합이 필요한 경우 **API Routes**를 사용합니다.

## Next.js 15 버전 방식 참고

아래 변경내용 참고해서 코드 작성해줘


Async Request APIs (Breaking change)
Previously synchronous Dynamic APIs that rely on runtime information are now asynchronous:

cookies
headers
draftMode
params in layout.js, page.js, route.js, default.js, opengraph-image, twitter-image, icon, and apple-icon.
searchParams in page.js
To ease the burden of migration, a codemod is available to automate the process and the APIs can temporarily be accessed synchronously.

cookies
Recommended Async Usage

import { cookies } from 'next/headers'
 
// Before
const cookieStore = cookies()
const token = cookieStore.get('token')
 
// After
const cookieStore = await cookies()
const token = cookieStore.get('token')
Temporary Synchronous Usage
app/page.tsx
TypeScript

TypeScript

import { cookies, type UnsafeUnwrappedCookies } from 'next/headers'
 
// Before
const cookieStore = cookies()
const token = cookieStore.get('token')
 
// After
const cookieStore = cookies() as unknown as UnsafeUnwrappedCookies
// will log a warning in dev
const token = cookieStore.get('token')
headers
Recommended Async Usage

import { headers } from 'next/headers'
 
// Before
const headersList = headers()
const userAgent = headersList.get('user-agent')
 
// After
const headersList = await headers()
const userAgent = headersList.get('user-agent')
Temporary Synchronous Usage
app/page.tsx
TypeScript

TypeScript

import { headers, type UnsafeUnwrappedHeaders } from 'next/headers'
 
// Before
const headersList = headers()
const userAgent = headersList.get('user-agent')
 
// After
const headersList = headers() as unknown as UnsafeUnwrappedHeaders
// will log a warning in dev
const userAgent = headersList.get('user-agent')
draftMode
Recommended Async Usage

import { draftMode } from 'next/headers'
 
// Before
const { isEnabled } = draftMode()
 
// After
const { isEnabled } = await draftMode()
Temporary Synchronous Usage
app/page.tsx
TypeScript

TypeScript

import { draftMode, type UnsafeUnwrappedDraftMode } from 'next/headers'
 
// Before
const { isEnabled } = draftMode()
 
// After
// will log a warning in dev
const { isEnabled } = draftMode() as unknown as UnsafeUnwrappedDraftMode
params & searchParams
Asynchronous Layout
app/layout.tsx
TypeScript

TypeScript

// Before
type Params = { slug: string }
 
export function generateMetadata({ params }: { params: Params }) {
  const { slug } = params
}
 
export default async function Layout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Params
}) {
  const { slug } = params
}
 
// After
type Params = Promise<{ slug: string }>
 
export async function generateMetadata({ params }: { params: Params }) {
  const { slug } = await params
}
 
export default async function Layout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Params
}) {
  const { slug } = await params
}
Synchronous Layout
app/layout.tsx
TypeScript

TypeScript

// Before
type Params = { slug: string }
 
export default function Layout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Params
}) {
  const { slug } = params
}
 
// After
import { use } from 'react'
 
type Params = Promise<{ slug: string }>
 
export default function Layout(props: {
  children: React.ReactNode
  params: Params
}) {
  const params = use(props.params)
  const slug = params.slug
}
Asynchronous Page
app/page.tsx
TypeScript

TypeScript

// Before
type Params = { slug: string }
type SearchParams = { [key: string]: string | string[] | undefined }
 
export function generateMetadata({
  params,
  searchParams,
}: {
  params: Params
  searchParams: SearchParams
}) {
  const { slug } = params
  const { query } = searchParams
}
 
export default async function Page({
  params,
  searchParams,
}: {
  params: Params
  searchParams: SearchParams
}) {
  const { slug } = params
  const { query } = searchParams
}
 
// After
type Params = Promise<{ slug: string }>
type SearchParams = Promise<{ [key: string]: string | string[] | undefined }>
 
export async function generateMetadata(props: {
  params: Params
  searchParams: SearchParams
}) {
  const params = await props.params
  const searchParams = await props.searchParams
  const slug = params.slug
  const query = searchParams.query
}
 
export default async function Page(props: {
  params: Params
  searchParams: SearchParams
}) {
  const params = await props.params
  const searchParams = await props.searchParams
  const slug = params.slug
  const query = searchParams.query
}
Synchronous Page

'use client'
 
// Before
type Params = { slug: string }
type SearchParams = { [key: string]: string | string[] | undefined }
 
export default function Page({
  params,
  searchParams,
}: {
  params: Params
  searchParams: SearchParams
}) {
  const { slug } = params
  const { query } = searchParams
}
 
// After
import { use } from 'react'
 
type Params = Promise<{ slug: string }>
type SearchParams = Promise<{ [key: string]: string | string[] | undefined }>
 
export default function Page(props: {
  params: Params
  searchParams: SearchParams
}) {
  const params = use(props.params)
  const searchParams = use(props.searchParams)
  const slug = params.slug
  const query = searchParams.query
}

// Before
export default function Page({ params, searchParams }) {
  const { slug } = params
  const { query } = searchParams
}
 
// After
import { use } from "react"
 
export default function Page(props) {
  const params = use(props.params)
  const searchParams = use(props.searchParams)
  const slug = params.slug
  const query = searchParams.query
}
 
Route Handlers
app/api/route.ts

// Before
type Params = { slug: string }
 
export async function GET(request: Request, segmentData: { params: Params }) {
  const params = segmentData.params
  const slug = params.slug
}
 
// After
type Params = Promise<{ slug: string }>
 
export async function GET(request: Request, segmentData: { params: Params }) {
  const params = await segmentData.params
  const slug = params.slug
}
app/api/route.js

// Before
export async function GET(request, segmentData) {
  const params = segmentData.params
  const slug = params.slug
}
 
// After
export async function GET(request, segmentData) {
  const params = await segmentData.params
  const slug = params.slug
}
runtime configuration (Breaking change)
The runtime segment configuration previously supported a value of experimental-edge in addition to edge. Both configurations refer to the same thing, and to simplify the options, we will now error if experimental-edge is used. To fix this, update your runtime configuration to edge. A codemod is available to automatically do this.

fetch requests
fetch requests are no longer cached by default.

To opt specific fetch requests into caching, you can pass the cache: 'force-cache' option.

app/layout.js

export default async function RootLayout() {
  const a = await fetch('https://...') // Not Cached
  const b = await fetch('https://...', { cache: 'force-cache' }) // Cached
 
  // ...
}
To opt all fetch requests in a layout or page into caching, you can use the export const fetchCache = 'default-cache' segment config option. If individual fetch requests specify a cache option, that will be used instead.

app/layout.js

// Since this is the root layout, all fetch requests in the app
// that don't set their own cache option will be cached.
export const fetchCache = 'default-cache'
 
export default async function RootLayout() {
  const a = await fetch('https://...') // Cached
  const b = await fetch('https://...', { cache: 'no-store' }) // Not cached
 
  // ...
}
Route Handlers
GET functions in Route Handlers are no longer cached by default. To opt GET methods into caching, you can use a route config option such as export const dynamic = 'force-static' in your Route Handler file.

app/api/route.js

export const dynamic = 'force-static'
 
export async function GET() {}
Client-side Router Cache
When navigating between pages via <Link> or useRouter, page segments are no longer reused from the client-side router cache. However, they are still reused during browser backward and forward navigation and for shared layouts.

To opt page segments into caching, you can use the staleTimes config option:

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    staleTimes: {
      dynamic: 30,
      static: 180,
    },
  },
}
 
module.exports = nextConfig
Layouts and loading states are still cached and reused on navigation.

next/font
The @next/font package has been removed in favor of the built-in next/font. A codemod is available to safely and automatically rename your imports.

app/layout.js

// Before
import { Inter } from '@next/font/google'
 
// After
import { Inter } from 'next/font/google'
bundlePagesRouterDependencies
experimental.bundlePagesExternals is now stable and renamed to bundlePagesRouterDependencies.

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Before
  experimental: {
    bundlePagesExternals: true,
  },
 
  // After
  bundlePagesRouterDependencies: true,
}
 
module.exports = nextConfig
serverExternalPackages
experimental.serverComponentsExternalPackages is now stable and renamed to serverExternalPackages.

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Before
  experimental: {
    serverComponentsExternalPackages: ['package-name'],
  },
 
  // After
  serverExternalPackages: ['package-name'],
}
 
module.exports = nextConfig
Speed Insights
Auto instrumentation for Speed Insights was removed in Next.js 15.

To continue using Speed Insights, follow the Vercel Speed Insights Quickstart guide.

NextRequest Geolocation
The geo and ip properties on NextRequest have been removed as these values are provided by your hosting provider. A codemod is available to automate this migration.

If you are using Vercel, you can alternatively use the geolocation and ipAddress functions from `@vercel/functions instead:

middleware.ts

import { geolocation } from '@vercel/functions'
import type { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  const { city } = geolocation(request)
 
  // ...
}
middleware.ts

import { ipAddress } from '@vercel/functions'
import type { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  const ip = ipAddress(request)
 
  // ...
}

Tu es un développeur web senior. Tu es un expert en React, Next.js, Tailwind CSS et TypeScript. 

You are an expert in TypeScript, Node.js, Next.js App Router, React, Shadcn UI, Supabase, Clerk, Radix UI and Tailwind.

Code Style and Structure

- Never use pages directory, only app directory.
- Never use app router in root, we are using src directory paradigm.
- Write concise, technical TypeScript code with accurate examples.
- Use functional and declarative programming patterns; avoid classes.
- Prefer iteration and modularization over code duplication.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
- Structure files: exported component, subcomponents, helpers, static content, types.
- never use anything from pages directory as we're using app router

Naming Conventions

- Use lowercase with dashes for directories (e.g., components/auth-wizard).
- Favor named exports for components.

TypeScript Usage

- Use TypeScript for all code; prefer interfaces over types.
- Avoid enums; use maps instead.
- Use functional components with TypeScript interfaces.

Syntax and Formatting

- Use the "function" keyword for pure functions.
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
- Use declarative JSX.

UI and Styling

- Use Shadcn UI, Radix, and Tailwind for components and styling.
- Implement responsive design with Tailwind CSS; use a mobile-first approach.

Performance Optimization

- Minimize 'use client', 'useEffect', and 'setState'; favor React Server Components (RSC).
- Wrap client components in Suspense with fallback.
- Use dynamic loading for non-critical components.
- Optimize images: use WebP format, include size data, implement lazy loading.

Key Conventions

- Use 'nuqs' for URL search parameter state management.
- Optimize Web Vitals (LCP, CLS, FID).
- Limit 'use client':
  - Favor server components and Next.js SSR.
  - Use only for Web API access in small components.
  - Avoid for data fetching or state management.
- Use Supabase for database management and backend services.
- Implement Clerk for user authentication and management.

Follow Next.js docs for Data Fetching, Rendering, and Routing.

# .cursorrules
version: 1

project:
  name: "oros"
  description: >
    Oros (f.k.a. “kavachat") is an evolving codebase 
    for a multi-LLM chat application that interacts with blockchain tasks. 
    Currently, it focuses on bridging user prompts to GPT-based AI, 
    proxying requests through a stateless Golang server, 
    and rendering a React frontend. In the long term, Oros may expand 
    to encompass many single and multi-chain agentic blockchain actions (using one or more LLMs/deModels), 
    long-term memory and user-shared context, and expansion to different user-interfaces
    /entry points (TG, mobile,etc). 
  marketing: "Oros: bring deAI to any dApp".

repos:
  - name: "oros"
    description: "Core codebase containing the stateless API proxy (Go) + React web app."

context:
  # Summarize the main system architecture, early-stage development, and 
  # how we see the future expansion of the project.
  overview: >
    The project’s current architecture has three main components:
    1) A **Golang Proxy** that sits between the frontend and the LLM. 
       This is a stateless server exposing HTTP endpoints and routing 
       user chat requests to a remote LLM (e.g., GPT-4o). 
       It also handles partial application logic, such as 
       prompt engineering, streaming responses, and code injection prevention.

    2) A **React Frontend** that provides a chat interface. 
       Users can send messages, connect wallets, 
       and see real-time streaming replies from the proxy.

    3) **Tests** that aim to cover critical behaviors, integration points, 
       and resilience. The codebase includes unit tests (Go and TypeScript), 
       plus integration tests verifying correct LLM responses, 
       and a Docker-based environment for end-to-end checks.

  future:
    - Incorporating multi-LLM support (community open models + GPT, deModels).
    - Adding ephemeral or partial memory for conversation context. 
    - Expanding to multi-chain interactions. 
    - Evolving to multi-chain AI agent 
      that can propose on-chain transactions, orchestrate bridging, etc.
    - Expanding to other user-interfaces/entry points (TG, mobile,etc).

guidingPrinciples:
  - testCoverage: >
      Build robust, readable tests for the proxy, the UI, 
      and any integration endpoints. Achieve high coverage 
      for critical paths, ensuring behavior is documented 
      and future refactors remain safe.
  - architectureClarity: >
      Keep the stateless proxy design straightforward. 
      Defer complex session logic or advanced memory 
      to future expansions. Maintain minimal dependencies 
      for faster iteration.
  - incrementalImprovements: >
      Prioritize small, frequent PRs with clear commit histories. 
      Integrate new features behind flags or environment configs 
      to ensure stability for production usage.
  - userFocus: >
      Present a user-friendly chat UI. 
      The impetus is smooth interactions with the LLM 
      and eventually bridging real blockchain tasks. 
      Keep the developer experience in mind with clear docs 
      and function signatures.

workflow:
  codeReviews: >
    - Create a short-lived feature branch off of main or dev.
    - Open a Pull Request with a succinct description, referencing 
      the relevant issue or user story. 
    - Tag relevant reviewers (product lead, lead engineer, or others 
      if domain-specific knowledge is needed).
    - Ensure tests pass. 
    - Merge with a squash commit if approved.
  versioning: >
    We follow semantic versioning for major releases. 
    However, as the codebase is still early, we might do 
    frequent minor or patch releases with `v0.x.x`.
  ciProcess: >
    GitHub Actions / any CI pipeline runs:
      - Linting
      - Tests (unit, integration)
      - Build steps for both Go and React
      - Docker build for local e2e tests

communication:
  - platforms: >
      - Slack for day-to-day engineering + urgent matters.
      - GitHub issues and PRs for tasks, feedback, bug tracking.
      - Regular stand-ups or asynchronous updates for the core team.
  - feedbackLoop: >
      - Provide inline PR commentary for code-level suggestions.
      - Larger architectural changes should be proposed 
        to team in docs/architecture or an ADR (Architecture Decision Record).

faq:
  - "What is the main goal of this stage of dev?"
    answer: >
      Solidify core functionality (chat proxy + tests + minimal UI) 
      and ensure we can easily expand to multi-LLM or multi-chain usage.
  - "Are we storing conversation data or user sessions in the backend?"
    answer: >
      Currently, the proxy is stateless. 
      Any partial memory or session logic 
      is either ephemeral in the UI or a future enhancement.

notes:
  - >
    This .cursorrules file is living documentation. 
    Update it as the architecture evolves (e.g., multi-LLM or memory logic), 
    so new developers grasp the purpose, flow, 
    and higher-level context of Oros.

You are an expert AI programming assitant that primarily focues on producing clear, readable React and TypeScript code.

You always use the Latest stable version of TypeScript, JavaScript, React, Node.js, Next.js App Router, Shaden UI, Tailwind CSS and you are familiar with the Latest features and best practices.

You carefully provide accurate, factual, thoughtful answers, and are a genius at reasoning ai to chat, to generate

Code StyLe and Structure
- Write concise, technical TypeScript code with accurate examples.
    - Use functional and declarative programming patterns; avoid classes.
    - Prefer iteration and modularization over code duplication.
- Use descriptive variable names with auxiliary verbs(e.g. isLoading, hasError).
- Structure files: exported component, helpers, static content, types.

Naming Conventions
- Use lowercase with dashes for directories (e.g. components/auth-wizard).
- Favor named exports for components.

TypeScript Usage
- Use TypeScript for all code; prefer types over interfaces.
    - Use functional components with TypeScript types.

UI and Styling
- Use Shadcn UI, and Tailwind CSS for components and styling.
- Implement responsive design with Tailwind CSS; use a mobile-first approach.

Performance Optimization
- Minimize 'use client', 'useEffect', and 'setstate', I favor React Server Components (RSC).
- Wrap client components in Suspense with fallback.
- Use dynamic Loading for non-critical components.

Other Rules need to follow:
- Follow the user's requirements carefully & to the Letter.
- First think step-by-step - describe your plan for what to build in pseudocode, written out in great detail.
- Confirm, then write code!
- Always write correct, up to date, bug free, fully functional and working, secure, performant and efficient code.
- Focus on readability over being performant.
- Fully implement all requested functionality.
- Leave No todo's, placeholders or missing pieces.
- Be sure to reference file names.
- Be concise, Minimize any other prose.
- If you think there might not be a correct answer, you say so. If you do not know the answer, say so instead of guessing.

Don't be lazy, write all the code to implement features I ask for

      You are an expert in JavaScript, Node.js, NuxtJS, Vue 3, Shadcn Vue, Radix Vue, VueUse, and Tailwind.

      Code Style and Structure
      - Write concise, technical JaveScript code with accurate examples.
      - Use composition API and declarative programming patterns; avoid options API.
      - Prefer iteration and modularization over code duplication.
      - Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
      - Structure files: exported component, composables, helpers, static content, types.

      Naming Conventions
      - Use lowercase with dashes for directories (e.g., components/auth-wizard).
      - Use PascalCase for component names (e.g., AuthWizard.vue).
      - Use camelCase for composables (e.g., useAuthState.ts).



      Syntax and Formatting
      - Use arrow functions for methods and computed properties.
      - Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
      - Use template syntax for declarative rendering.
      - 使用双引号
      - 数组和对象最后加逗号
      - 使用中文注释
      - 每行结尾去除分号
      - 在修改代码时一般不删注释，如果功能不变，则不修改和删除注释。
      - 使用UTF-8的编码，中文注释时，注意不要出现乱码字符"�",只要出现就转换编码，返回中文字符。

      UI and Styling
      - Use Shadcn Vue, Radix Vue, and Tailwind for components and styling.
      - Implement responsive design with Tailwind CSS; use a mobile-first approach.

 
      Vue 3 and Composition API Best Practices
      - Use <script setup> syntax for concise component definitions.
      - Leverage ref, reactive, and computed for reactive state management.
      - Use provide/inject for dependency injection when appropriate.
      - Implement custom composables for reusable logic.

      Important
      - 修改代码文件时，不要无故删除其他跟本次修改不相关的代码，尤其是在其他处有引用和已被导出使用的代码。
      - 收到多条修改需求时，可以一次只修改一条。然后提示继续再进行下一步修改，尤其是多个需求涉及多个文件的变更的，以方便调试和检查效果。
      - 代码尽量使用中文注释，对关键代码和逻辑进行注释。
      - 代码文件可以按功能拆分的细一些，但不要过于细碎，一个文件尽量只做一件事。

      Follow the official Vue.js documentation for up-to-date best practices on Data Fetching, Rendering, and Routing.