Enterprise-grade development standards for TypeScript/React applications with Material UI, emphasizing tree-shakeable imports, component organization, type safety, and mandatory linting
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.
This skill enforces:
**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';
```
**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'; // ❌
```
**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
}
```
**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)
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`
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)
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
Before declaring any task complete, verify:
```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
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/cursorrules-database-development-rules/raw