.cursorrules Next.js Vercel TypeScript

by @Oleksii Bondarenko

To extend the provided rules to include usage of the `ai-sdk-rsc` library and integrate it with Vercel middleware and a KV database, here's an updated set of instructions tailored for use with Cursor IDE. These instructions are designed to help you effectively implement generative user interfaces using React Server Components (RSC) with the AI SDK.

### Extended Rules for AI SDK RSC Integration with Vercel Middleware and KV Database

**Environment and Tools**

- You are an expert in TypeScript, Node.js, Next.js App Router, React, Shadcn UI, Radix UI, Tailwind, and Vercel middleware.
- You are familiar with Vercel's KV database for managing stateful data.

**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, subcomponents, 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 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 UI, 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.
- Follow Next.js docs for Data Fetching, Rendering, and Routing.

**AI SDK RSC Integration**

- **Setup and Installation**: Integrate `ai-sdk-rsc` into your Next.js project.
  - Install the library using `npm install ai-sdk-rsc` or `yarn add ai-sdk-rsc`.
  - Configure middleware in `middleware.ts` to manage requests and sessions using Vercel's KV database.

- **Middleware Implementation**: Use Vercel middleware to handle incoming requests.
  - Create a middleware file in the `middleware` directory (e.g., `middleware/ai-middleware.ts`).
  - Use middleware to parse user input and manage sessions with the KV database.
  - Example:
    ```typescript
    import { NextRequest, NextResponse } from 'next/server';
    import { kv } from '@vercel/kv';

    export async function middleware(req: NextRequest) {
      const sessionId = req.cookies.get('session-id');
      if (!sessionId) {
        const newSessionId = generateSessionId();
        await kv.set(newSessionId, { state: {} }); // Initialize state in KV database
        const res = NextResponse.next();
        res.cookies.set('session-id', newSessionId);
        return res;
      }
      // Fetch state from KV database
      const state = await kv.get(sessionId);
      req.nextUrl.searchParams.set('state', JSON.stringify(state));
      return NextResponse.next();
    }

    function generateSessionId() {
      return Math.random().toString(36).substring(2);
    }
    ```

- **React Server Components (RSC) and AI SDK**:
  - Use `ai-sdk-rsc` hooks to manage state and stream generative content.
  - Example usage of AI SDK hooks in a React Server Component:
    ```typescript
    import { useAIStream } from 'ai-sdk-rsc';
    import { FC } from 'react';

    interface ChatProps {
      initialMessage: string;
    }

    const Chat: FC = ({ initialMessage }) => {
      const { messages, sendMessage } = useAIStream({
        initialMessage,
        onMessage: (message) => console.log('New message:', message),
      });

      return (
        {msg.content}
      );

    export default Chat;
    ```

- **KV Database Integration**:
  - Use Vercel's KV database to store and retrieve session data.
  - Utilize `kv.set`, `kv.get`, and `kv.delete` to manage data.
  - Ensure the database operations are asynchronous to avoid blocking server-side rendering (SSR).

- **Data Fetching and State Management**:
  - Use Next.js data fetching methods (`getServerSideProps`, `getStaticProps`) to manage server-side state.
  - Avoid client-side data fetching methods (`useEffect`, `fetch`) except for critical, non-blocking operations.

- **Deployment Considerations**:
  - Ensure all environment variables (e.g., API keys, database credentials) are securely stored in Vercel's environment settings.
  - Configure Vercel's KV and other serverless functions correctly to handle scalability and performance needs.

By following these extended rules, you'll be able to create a well-optimized, scalable, and efficient Next.js application that leverages `ai-sdk-rsc`, Vercel middleware, and KV database for building sophisticated AI-driven interfaces.

AI Application Development Toolkit

A suite of tools leveraging AI SDK RSC, Vercel middleware, and KV databases for building scalable, real-time AI-powered solutions.

AI-Driven Applications

Customer Support Chatbot:
Manages persistent chat sessions via KV database, with AI-driven responses using RSC.
Content Generator for Bloggers:
Creates blog drafts via AI SDK RSC, stores user preferences in KV, and updates UI with React Server Components.

Real-Time Tools

Real-Time Translation Tool:
Processes language translation via AI SDK, tracks sessions with KV, and optimizes requests via Vercel middleware.
Music Composition Assistant:
Generates music ideas using AI SDK, stores patterns in KV, and provides interactive feedback via React.

Personalized Systems

Personalized News Aggregator:
Uses AI SDK RSC to learn preferences, stores data in KV, and delivers tailored content via server-side fetching.
Language Learning App:
Enables real-time conversation practice with AI, tracks progress in KV, and manages sessions via Vercel middleware.

Collaboration & Education

AI-Enhanced Code Collaboration Tool:
Offers real-time code suggestions via AI SDK and persists session states in KV.
Interactive Virtual Tutor:
Generates educational content with AI SDK, tracks student progress in KV, and handles sessions via middleware.

Dynamic Solutions

Interactive Storytelling Platform:
Renders dynamic storylines via React Server Components, stores user choices in KV.
E-commerce Recommendation Engine:
Uses AI to suggest products based on KV-stored user history and optimizes requests via Vercel middleware.

Key Technologies:

AI SDK RSC (AI processing)
Vercel Middleware (request handling)
Vercel KV Database (session/data persistence)
React Server Components (dynamic rendering)

Overview of .cursorrules prompt

The .cursorrules file provides a comprehensive set of guidelines for integrating the ai-sdk-rsc library with Vercel middleware and a KV database within a Next.js application. It outlines best practices for utilizing TypeScript, React Server Components, and Shadcn/Radix UI, emphasizing modularity, performance optimization, and styling. The file includes instructions on setting up middleware in middleware.ts, managing user sessions with Vercel’s KV database, and using AI SDK hooks for generative content streaming. It also covers data fetching strategies, state management, and deployment considerations to ensure a scalable and efficient application.

Updated: March 17, 2025

Developers skilled in Next.js and TypeScript can build scalable, efficient AI-driven interfaces using React Server Components, Vercel middleware, and KV databases.

Usefull for: