Shipixen Cursor Rules: What They Are and Why They Matter

# Adding a Blog Post

This rule explains how to add a new blog post to the project, including required frontmatter fields and document properties. It references @`contentlayer.config.ts`, @`code.mdx`, and @`using-the-blog.mdx`.

## 1. Create a New Markdown File

- Add your `.mdx` file to the `data/` directory or a subfolder (nested routes are supported).
- The file name becomes the slug for the article.

## 2. Add Frontmatter

Frontmatter is a YAML block at the top of your file that defines metadata for the post. Required and optional fields are defined in @`contentlayer.config.ts` and demonstrated in @`using-the-blog.mdx`.

When writing arrays in frontmatter, use the syntax `- item` for each element. For example:

\```yaml
tags:
  - 'tag1'
  - 'tag2'
\```

### Example Frontmatter
\```yaml
title: 'Blog post title'           # Required
summary: 'A short summary'         # Optional but recommended
date: '2023-01-01'                 # Required (YYYY-MM-DD), use today's date
tags:                              # Optional, array of strings
  - 'next-js'
  - 'guide'
lastmod: '2023-02-01'              # Optional, last modified date
images:                            # Optional, array of image paths
  - '/static/images/img.webp'
authors:
  - 'default'                      # Optional, array of author IDs
layout: 'PostLayout'               # Optional, see below
draft: false                       # Optional, set true to hide
canonicalUrl: 'https://...'        # Optional, canonical link
\```

## 3. Supported Layouts

Specify the layout in frontmatter with the `layout` field. Available layouts (see @`using-the-blog.mdx`):
- `PostLayout` (default)
- `PostLayoutWithToc`
- `PostSimple`
- `PostBanner`

## 4. Document Properties (from @`contentlayer.config.ts`)

- `title` (string, required): The post title
- `date` (date, required): Publish date
- `tags` (string[], optional): Tags for the post
- `lastmod` (date, optional): Last modified date
- `draft` (boolean, optional): If true, post is hidden
- `summary` (string, optional): Short summary
- `images` (json, optional): Array of image paths
- `authors` (string[], optional): Author IDs (see `data/authors/`)
- `layout` (string, optional): Layout component
- `canonicalUrl` (string, optional): Canonical URL

## 5. Writing Content

- Use Markdown and MDX for content, including code blocks, images, tables, and custom components.
- See @`using-the-blog.mdx` for syntax and examples.

## 6. Table of Contents

- Use the `<TOCInline toc={props.toc} asDisclosure />` component to add an inline table of contents to your post.

## 7. Nested Routes

- Organize posts in subfolders under `data/` for nested routes (e.g., `data/guides/my-guide.mdx`).

## 8. Drafts

- Set `draft: true` in frontmatter to hide a post from the blog.

Refer to this rule and the example files for a complete guide to adding and formatting blog posts.

# Landing Page Components Rule

When building public-facing pages (e.g., landing, features, contact) under `/app`, use components from the `@landing` module. These components are designed for rapid, consistent, and visually appealing landing page development.

## Component Source

- Import all landing page components from @@/components/landing
- Use shared UI elements (e.g., `Button`) from @@/components/shared/ui.
- Use icons from `lucide-react` for consistent iconography.
- Use `Image` from `next/image` for optimized images.

## Documentation

- Refer to the official documentation for usage and props: @Landing Page Components Documentation

## Example Structure

A typical landing page should:
- Compose sections using the following components:
  - `LandingHeader`, `LandingHeaderMenuItem`
  - `LandingPrimaryImageCtaSection`
  - `LandingProductFeaturesGrid`, `LandingProductFeature`
  - `LandingFeatureList`
  - `LandingProductTourSection`, `LandingProductTourList`, `LandingProductTourTrigger`, `LandingProductTourContent`
  - `LandingTestimonialGrid`
  - `LandingPricingSection`, `LandingPricingPlan`
  - `LandingFaqCollapsibleSection`
  - `LandingSaleCtaSection`
  - `LandingFooter`, `LandingFooterColumn`, `LandingFooterLink`
  - `LandingBandSection`
- Use arrays for feature, benefit, testimonial, and FAQ items, mapping over them to render lists.
- Use Tailwind CSS for layout and spacing, following the project's @tailwind-styling.mdc
- @tail
- Use a mobile-first, responsive approach.

## Best Practices

- Use only the documented props for each component.
- Compose sections in a logical, user-friendly order.
- Follow the project's code style, React, and Next.js best practices @nextjs.mdc.

For more details, always refer to the @Landing Page Components Documentation.

You are an expert in TypeScript, React, Node.js, Next.js App Router, Shadcn UI, TailwindCSS.

## Code Style and Structure

- Write concise, technical TypeScript code using the rules below
- 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

## Rules

- No unused variables.
- For multi-line if statements, use curly braces.
- Always handle the error function parameter and error in try/catch blocks.
- Use camelcase for variables and functions.
- Use PascalCase for constructors and React components.

## Naming Conventions

- Use lowercase with dashes for directories (e.g., components/auth-wizard).
- Use named exports; avoid default exports (e.g. export const Button = () => {})

# React Best Practices

- Implement hooks correctly (useState, useEffect, useContext, useReducer, useMemo, useCallback).
- Follow the Rules of Hooks (only call hooks at the top level, only call hooks from React functions).
- Create custom hooks to extract reusable component logic.
- Prefer composition over inheritance.
- Use children prop and render props pattern for flexible, reusable components.
- Implement React.lazy() and Suspense for code splitting.
- Use refs sparingly and mainly for DOM access.
- Prefer controlled components over uncontrolled components.
- Implement error boundaries to catch and handle errors gracefully.
- Use cleanup functions in useEffect to prevent memory leaks.
- Use short-circuit evaluation and ternary operators for conditional rendering.
- Use dynamic loading for non-critical components.

## UI and Styling

- Use Shadcn UI for component foundations from @`@/components/shared/ui`
- Implement responsive design with Tailwind CSS; use a mobile-first approach.
- Use Tailwind for utility classes and rapid prototyping.
- Implement dark mode support

## Forms and Validation

- Use controlled components for form inputs.
- Implement form validation (client-side and server-side).
- Consider using libraries like react-hook-form for complex forms.
- Use Zod for schema validation.

## Page Metadata

- **For page metadata, use the Shipixen utility:**
  - Use `genPageMetadata` from ](mdc:app/seo.tsx) for all page meta generation.

  **Example:**
  \```ts
  import { genPageMetadata } from '@/app/seo';
  export const metadata = genPageMetadata({ title: 'Home', description: 'Welcome!' });
  \```

## Error Handling and Validation

- Prioritize error handling and edge cases.
- Handle errors and edge cases at the beginning of functions.
- Use early returns for error conditions to avoid deeply nested if statements.
- Place the happy path last in the function for improved readability.
- Avoid unnecessary else statements; use if-return pattern instead.
- Use guard clauses to handle preconditions and invalid states early.
- Implement proper error logging and user-friendly error messages.

## Accessibility (a11y)

- Use semantic HTML elements.
- Implement proper ARIA attributes.
- Ensure keyboard navigation support.

## Security

- Sanitize user inputs to prevent XSS attacks.
- Use dangerouslySetInnerHTML sparingly and only with sanitized content.

Follow latest Next.js conventions for Data Fetching, Rendering, and Routing. See @Next.js Documentation

# Project Structure Guide

This rule explains the folder structure of the project. Use this as a reference for navigating and understanding the codebase.

## Root Directory

The root contains configuration files and the main project folders:
- @package.json: Project dependencies and scripts
- @tsconfig.json: TypeScript configuration
- @next.config.js: Next.js configuration
- @tailwind.config.js: Tailwind CSS configuration
- @contentlayer.config.ts: Contentlayer setup for MDX/content

## Key Directories

### @components/

Reusable React components, organized by feature:

- `blog/`: Blog-specific UI components
- `landing/`: Landing page components
- `shared/`: Shared UI primitives (often Shadcn-based)
- `search/`: Search UI components
- `icons/`: SVG and icon components
- `MDXComponents.tsx`: MDX element renderers. Each element that should be rendered in the blog needs to be added here.

### @layouts/

Page and post layout components, including list and post layouts, author layouts, and banners.

### @data/

Content and configuration data:

- `authors/`: Author profiles
- `config/`: Site configuration
- `.mdx` files: Content pages - any mdx file in here will be rendered as a blog post
- `app-info.ts`: App metadata (auto-generated)

### @app/

Next.js App Router directory. Contains all route definitions and API endpoints:

- `page.tsx`: Main entry point
- `layout.tsx`: Root layout
- `not-found.tsx`: 404 page
- `seo.tsx`, `theme-providers.tsx`: SEO and theme context
- Subfolders for routes: `about/`, `tags/`, `api/`, `terms/`, `pricing/`, `privacy/`, etc.
- Dynamic routes: `[...slug]/`, `all-articles/`

### @scripts/

Node scripts for build, RSS generation, and app info automation.

### @css/

Global and syntax highlighting CSS files.

### @lib/

Utility functions and helpers.

### @components/shared/

**Shared Components**: Common UI and logic used across the app, including:
- `Header.tsx`: Main site header, navigation, and theme switcher. Uses `headerNavLinks` from config.
- `Footer.tsx`: Main site footer, renders columns and social links using `footerLinks` and `siteConfig`.
- `MobileNav.tsx`, `ScrollTop.tsx`, `ThemeSwitch.tsx`, `Analytics.tsx`, `PageTitle.tsx`, `SectionContainer.tsx`, `VideoPlayer.tsx`, `ActiveLink.tsx`, `Link.tsx`, `FooterSupportButton.tsx`, `Image.tsx`: Utility and layout components for navigation, theming, analytics, and content display.
- `SearchProvider.tsx`: Context provider for search functionality.
- `useThemeSwitch.tsx`: Custom hook for theme toggling.
- **@ui/**: Shadcn-based UI primitives (buttons, toggles, dialogs, forms, etc.) for consistent design system usage. Example primitives:
  - `button.tsx`: Button component with multiple variants and sizes.
  - `toggle.tsx`: Toggle switch using Radix UI and class-variance-authority.
  - `dropdown-menu.tsx`, `menubar.tsx`, `pagination.tsx`, `calendar.tsx`, `card.tsx`, `table.tsx`, `tabs.tsx`, `select.tsx`, `sheet.tsx`, `slider.tsx`, `switch.tsx`, `badge.tsx`, `dialog.tsx`, `alert.tsx`, `avatar.tsx`, `form.tsx`, etc.
  - All primitives are designed for accessibility, theme support, and composability.

### @data/config/

**Configuration Directory**: Centralized site and UI configuration:
- `site.settings.js`: Main site config (title, description, analytics, newsletter, search, etc.), imported as `siteConfig`.
- `siteSettingsInterface.ts`: TypeScript interface for site config and metadata.
- `metadata.js`: Site metadata (title, description, domain, social links, theme, etc.).
- `footerLinks.ts`: Footer navigation columns and links.
- `headerNavLinks.ts`: Header navigation links, referencing `siteConfig` for dynamic paths.
- `colors.js`: Semantic color palette for Tailwind and UI.
- `pricingData.tsx` & `pricingDataInterface.ts`: Pricing tiers, frequencies, and types for pricing pages.
- `searchLinks.ts`: Quick navigation/search links for the app.

These config files are imported throughout the app and components to ensure consistent navigation, theming, and business logic.

## Other Notable Folders

- `.cursor/`: Cursor AI rules and metadata
- `public/`: Static assets

Refer to this rule for a high-level overview of the project structure and the purpose of each directory.

## Rule Improvement Triggers

- New code patterns not covered by existing rules
- Repeated similar implementations across files
- Common error patterns that could be prevented
- New libraries or tools being used consistently
- Emerging best practices in the codebase

# Analysis Process:
- Compare new code with existing rules
- Identify patterns that should be standardized
- Look for references to external documentation
- Check for consistent error handling patterns
- Monitor test patterns and coverage

# Rule Updates:

- **Add New Rules When:**
  - A new technology/pattern is used in 3+ files
  - Common bugs could be prevented by a rule
  - Code reviews repeatedly mention the same feedback
  - New security or performance patterns emerge

- **Modify Existing Rules When:**
  - Better examples exist in the codebase
  - Additional edge cases are discovered
  - Related rules have been updated
  - Implementation details have changed

- **Example Pattern Recognition:**

  \```typescript
  // If you see repeated patterns like:
  const data = await prisma.user.findMany({
    select: { id: true, email: true },
    where: { status: 'ACTIVE' }
  });

  // Consider adding to @prisma.mdc:
  // - Standard select fields
  // - Common where conditions
  // - Performance optimization patterns
  \```

- **Rule Quality Checks:**
- Rules should be actionable and specific
- Examples should come from actual code
- References should be up to date
- Patterns should be consistently enforced

## Continuous Improvement:

- Monitor code review comments
- Track common development questions
- Update rules after major refactors
- Add links to relevant documentation
- Cross-reference related rules

## Rule Deprecation

- Mark outdated patterns as deprecated
- Remove rules that no longer apply
- Update references to deprecated rules
- Document migration paths for old patterns

## Documentation Updates:

- Keep examples synchronized with code
- Update references to external docs
- Maintain links between related rules
- Document breaking changes

Follow @cursor_rules.mdc for proper rule formatting and structure.

# Tailwind CSS Styling Practices

This rule outlines our Tailwind CSS styling conventions.

## Class Organization

Organize Tailwind classes in logical groups:

1. Layout/positioning classes first
2. Sizing classes
3. Spacing (margin/padding)
4. Visual styles (colors, borders)
5. Typography
6. Interactive states
7. Responsive variants last

Example:
\```tsx
className="flex flex-col gap-4 w-full p-6 bg-primary-100/20 text-sm hover:bg-primary-200/30 md:flex-row"
\```

## Responsive Design

- Mobile-first approach (base classes for mobile, prefixed classes for larger screens)
- Use responsive prefixes: `sm:`, `md:`, `lg:`, `xl:`, `2xl:`

## Color System

- Use semantic color naming with numeric scale (primary-100, primary-900)
- Apply opacity with slash notation: `bg-primary-100/20`
- Use consistent dark mode variants: `dark:bg-primary-900/10`

\```tsx
className="bg-primary-100/20 text-primary-900 dark:bg-primary-900/10 dark:text-primary-100"
\```

## Layout Patterns

- Use flex and grid for layouts
- Use gap utilities instead of margins between flex/grid children
- Container classes for width constraints: `container-narrow`, `container-wide`, `container-ultrawide`, `max-w-sm` etc.

## Design System Integration

- Use consistent color palette (primary, secondary)
- Use consistent spacing scale
- Apply opacity for subtle UI elements
- Use gradient backgrounds for visual interest

\```tsx
className="bg-gradient-to-r from-gray-50/5 via-gray-100/60 to-gray-50/5"
\```

# TypeScript Code Style Guide

This rule defines the TypeScript code style conventions for the project. Follow these rules for all TypeScript and React code.

## Parameter Passing

- **Always pass parameters as a single object** (named parameters pattern).

  **Example:**
  \```ts
  // Good
  function doSomething({ id, name }: { id: string; name: string }) { /* ... */ }
  // Bad
  function doSomething(id: string, name: string) { /* ... */ }
  \```

## Type Safety

- **Never use `any` as a type.** Use explicit types, interfaces, or `unknown` with type guards if necessary.
- **Reuse interfaces** and place them in a `models/` directory when shared across files.

  **Example:**
  \```ts
  // models/user.ts
  export interface User { id: string; name: string; }
  // Usage
  import { User } from '@/models/user';
  \```

## Imports

- **Use shorter imports** via path aliases (e.g., `@/components/...`), not relative paths like `../../components`.
- **Do not use index exports.** Use named exports and import modules directly.

  **Example:**
  \```ts
  // Good
  import { Button } from '@/components/shared/ui/button';
  // Bad
  import { Button } from '@/components/shared/ui';
  \```

## Functional Programming

- **Do not use classes.** Use functional methods and hooks.
- **Always wrap `if` statements in curly braces**, even for single-line blocks.

  **Example:**
  ```ts
  // Good
  if (isActive) {
    doSomething();
  }
  // Bad
  if (isActive) doSomething();
  \```

## Comments and Documentation

- **Do not comment obvious things.**
- **Do not explain changes in comments.**
- **Only document extraordinary changes or complex logic.**
- **Use JSDoc or a short description for top-level functions.**

## Forms and Schemas

- **Reuse schemas** for forms (e.g., Zod schemas) and validation logic. Place schemas in a `schemas/` directory if shared.

## Utility Functions

- **Place small utility functions under `utils/function-name.ts`**.

  **Example:**
  \```ts
  // utils/format-date.ts
  export function formatDate(date: Date): string { /* ... */ }
  \```

# UI Components from @ui (Shadcn UI)

## Overview

All components imported from `@/components/shared/ui` are @Shadcn UI primitives. These components serve as the foundation for building user interfaces in this codebase.

## Usage Guidelines

- **Always prefer importing UI primitives from @@/components/shared/ui if available**
- **Do not duplicate UI logic**—extend or compose existing @@/components/shared/ui components if additional functionality is needed.
- **Follow the design system**: All @@/components/shared/ui components are styled with Tailwind CSS and follow the project's design tokens and accessibility standards.
- **Use named imports**: Example:
  \```tsx
  import { Button } from '@/components/shared/ui/button';
  \```
- **Reference the implementation**: If you need to customize or debug a component, check `@/components/shared/ui`

## When to use `@/components/shared/ui` components

- For all buttons, forms, dialogs, menus, and other UI primitives, use the corresponding @@/components/shared/ui component.
- For custom UI, compose with @@/components/shared/ui components as building blocks.
- Only use third-party or custom UI code if a suitable @@/components/shared/ui component does not exist and cannot be composed.

## Example

\```tsx
import { Button } from '@/components/shared/ui/button';
import { Input } from '@/components/shared/ui/input';
import { Dialog } from '@/components/shared/ui/dialog';

function ExampleForm() {
  return (
    <Dialog>
      <form className="flex flex-col gap-4">
        <Input label="Email" type="email" />
        <Button type="submit">Submit</Button>
      </form>
    </Dialog>
  );
}
\```

## Best Practices

- Use composition and props to extend functionality.
- Follow accessibility and responsive design patterns as established in the codebase.
- Prefer functional, declarative usage and avoid class-based components.

---

**See also:** @tailwind-styling.mdc, @nextjs.mdc