Cursorrules Database Development Rules

Enterprise-grade development standards for TypeScript/React applications with Material UI. This skill enforces strict patterns for imports, component organization, type safety, and code quality to prevent bundle bloat and maintain high code standards.

Core Principles

This skill enforces:

Instructions for AI Agent

1. Material UI Imports (CRITICAL - Bundle Impact)

**ALWAYS enforce tree-shakeable imports. This is a pre-push hook requirement.**

When writing Material UI code:

1. **Import components one per line from specific paths**:

```typescript

// ✅ CORRECT

import Button from '@mui/material/Button';

import Box from '@mui/material/Box';

import SearchIcon from '@mui/icons-material/Search';

```

2. **NEVER use destructured imports**:

```typescript

// ❌ FORBIDDEN - Bloats bundle by 500KB+

import { Button, Box } from '@mui/material';

import { Search } from '@mui/icons-material';

```

3. **Use `import type` for TypeScript types**:

```typescript

// ✅ CORRECT

import type { PaletteMode } from '@mui/material';

import type { SvgIconProps } from '@mui/material/SvgIcon';

```

4. **Common component paths quick reference**:

- Layout: `Box`, `Container`, `Grid`, `Stack`

- Inputs: `Button`, `TextField`, `Select`, `MenuItem`, `Checkbox`, `Switch`

- Feedback: `Alert`, `Dialog`, `Snackbar`, `CircularProgress`

- Data: `Table`, `TableBody`, `TableCell`, `TableHead`, `TableRow`, `Chip`, `Tooltip`

- Navigation: `Tabs`, `Tab`, `Drawer`

- Utils: `IconButton`, `Divider`, `Paper`, `Typography`

5. **Hooks come from `/styles`**:

```typescript

import { useTheme, styled } from '@mui/material/styles';

```

2. Component File Organization (MANDATORY)

**Every component MUST follow the `index.tsx` pattern.**

When creating or organizing components:

1. **Directory structure**:

```

ComponentName/

├── index.tsx # Main component (REQUIRED)

├── SubComponent.tsx # Sub-components if needed

├── helpers.ts # Component-specific utilities

├── types.ts # Component-specific types

└── styles.css # Component-specific styles

```

2. **Naming rules**:

- ✅ Component directories: `PascalCase`

- ✅ Main file: always `index.tsx`

- ✅ Sub-components: `PascalCase.tsx` in same directory

- ✅ Utilities: `camelCase.ts` (`helpers.ts`, `utils.ts`, `types.ts`)

- ❌ NEVER: `MyComponent/MyComponent.tsx` (redundant)

3. **When to create subdirectories**:

- Complex components with multiple sub-components

- Shared utilities: use `shared/` or `common/` directory

- Related pages: group under parent (e.g., `admin-console/maps-page/`, `admin-console/accounts-page/`)

4. **Import benefits**:

```typescript

// ✅ Clean imports from index.tsx

import ThemeToggle from '../common/theme-toggle';

// vs redundant naming

import ThemeToggle from '../common/theme-toggle/ThemeToggle'; // ❌

```

3. TypeScript Type Safety (CRITICAL)

**Absolute zero-tolerance for type safety violations.**

When writing TypeScript code:

1. **FORBIDDEN practices**:

- ❌ **NEVER use `any` type** - Always use specific types or `unknown`

- ❌ **NEVER use `@ts-ignore` or `@ts-expect-error`** without explicit user approval

- ❌ **NEVER leave implicit `any`** from untyped parameters

2. **Import proper types from libraries**:

```typescript

// ✅ CORRECT - Import domain types

import { Topic, Designer } from '@wisemapping/mindplot';

import type { ReactNode } from 'react';

```

3. **Handle nullable types correctly**:

```typescript

// ✅ CORRECT - Explicit nullable handling

const getTopicDepth = (topic: Topic): number => {

let current: Topic | null = topic;

while (current && current.getParent() !== null) {

current = current.getParent(); // Returns Topic | null

}

};

```

4. **Use `unknown` for truly unknown types**:

```typescript

// ✅ For JSON parsing or external data

const data: unknown = JSON.parse(str);

if (typeof data === 'object' && data !== null) {

// Type guard before use

}

```

4. Mandatory Linting Workflow (ENFORCED)

**AI MUST check linter after EVERY file creation or modification.**

**Strict workflow**:

1. **After creating/modifying each file**:

```

Step 1: Write/modify code

Step 2: IMMEDIATELY run linter on that specific file

Step 3: Fix ALL errors found

Step 4: Re-run linter to verify fixes

Step 5: Only then proceed to next file

```

2. **Before completing any task**:

```

Step 1: Run linter on ALL modified files together

Step 2: Fix any remaining issues

Step 3: Final verification pass

Step 4: Task complete

```

3. **How to run lints** (adjust to actual project commands):

- If using custom tooling: check specific files only

- Avoid running linter on entire codebase (too noisy)

- Focus on files you created/modified

4. **Common ESLint rules to follow**:

- `@typescript-eslint/no-explicit-any` - No `any` types

- `@typescript-eslint/no-unused-vars` - Remove unused imports/variables

- `@typescript-eslint/explicit-function-return-type` - Type function returns

- Proper null/undefined handling

- Material UI tree-shakeable imports

5. **Priority**:

- ✅ ZERO linting errors in completed tasks

- ✅ Fix ALL errors before declaring task complete

- ✅ Discuss with user if a rule seems incorrect (don't bypass silently)

5. Code Standards

When writing any code:

1. **Language**: Always use TypeScript over JavaScript

2. **React**: Use functional components + hooks (no class components)

3. **Naming conventions**:

- Components: `PascalCase` (`MyComponent.tsx`)

- Utilities: `camelCase` (`myUtility.ts`)

- Constants: `UPPER_SNAKE_CASE` (`MAX_VALUE`)

4. **Git practices**:

- Clear, descriptive commit messages

- Never force push to `main` branch

- Branch naming: `feature/name`, `fix/name`, `refactor/name`

6. Performance Considerations

When adding dependencies or creating components:

1. **Check for duplicate dependencies** before adding new packages

2. **Use dynamic imports** for code splitting when appropriate:

```typescript

const HeavyComponent = lazy(() => import('./HeavyComponent'));

```

3. **Run bundle analysis** if available (`yarn build:analyze` or equivalent)

4. **Verify Material UI imports** are tree-shakeable (see rule #1)

7. Testing Standards

When writing tests:

1. **Unit tests**: Name files `*.test.ts` or `*.test.tsx`

2. **Integration tests**: Use project's testing framework (e.g., Cypress)

3. **Coverage**: Aim for high coverage on critical business logic paths

4. **Co-locate tests**: Place test files next to components when appropriate

Task Completion Checklist

Before declaring any task complete, verify:

Example Workflow

```typescript

// Step 1: Create component with proper structure

// theme-toggle/index.tsx

import Switch from '@mui/material/Switch'; // ✅ Tree-shakeable

import IconButton from '@mui/material/IconButton'; // ✅ Tree-shakeable

import LightIcon from '@mui/icons-material/LightMode';

import DarkIcon from '@mui/icons-material/DarkMode';

import type { FC } from 'react'; // ✅ Type import

interface ThemeToggleProps {

mode: 'light' | 'dark'; // ✅ Proper typing

onToggle: (mode: 'light' | 'dark') => void;

}

const ThemeToggle: FC<ThemeToggleProps> = ({ mode, onToggle }) => {

return (

<IconButton onClick={() => onToggle(mode === 'light' ? 'dark' : 'light')}>

{mode === 'light' ? <DarkIcon /> : <LightIcon />}

</IconButton>

);

};

export default ThemeToggle;

// Step 2: IMMEDIATELY run linter on this file

// Step 3: Fix any errors found

// Step 4: Verify with second linter pass

// Step 5: Task complete

```

Notes