Best Practices

Code Organization

Directory Structure

packages/plugins/my-plugin/
├── src/
│   ├── components/     # UI components
│   ├── server/         # tRPC routers
│   ├── hooks/          # Custom hooks
│   ├── lib/            # Utilities
│   ├── types.ts        # TypeScript types
│   ├── manifest.ts     # Plugin manifest
│   └── index.ts        # Exports

Component Organization

• One component per file
• Export from index.ts
• Group related components in subdirectories
• Use TypeScript for all code

Performance

Optimize Queries

// ✅ GOOD: Fetch only what you need
const { data } = trpc.timer.getEntries.useQuery({
  workUnitId,
  select: ['id', 'startTime', 'duration'],
  limit: 50,
});

// ❌ BAD: Fetch all data
const { data } = trpc.timer.getAllData.useQuery();

Memoize Expensive Calculations

const expensiveValue = useMemo(() => {
  return calculateComplexMetric(data);
}, [data]);

Debounce User Input

const [searchQuery, setSearchQuery] = useState('');
const debouncedSearch = useDebouncedValue(searchQuery, 300);

useEffect(() => {
  performSearch(debouncedSearch);
}, [debouncedSearch]);

Error Handling

export function MyComponent() {
  const { data, isLoading, error } = trpc.getData.useQuery();

  if (isLoading) return <Loader />;

  if (error) {
    return (
      <Alert color="error">
        Failed to load data: {error.message}
      </Alert>
    );
  }

  return <DataDisplay data={data} />;
}

Type Safety

// Define typed props
interface MyTabProps {
  context: WorkUnitContext;
  config: PluginConfig;
}

// Use typed hooks
const { data } = trpc.myPlugin.getData.useQuery<DataType>({ id });

// Type guards
function isWorkUnit(entity: any): entity is WorkUnit {
  return entity && typeof entity.id === 'string';
}

Testing

import { render, screen } from '@testing-library/react';
import { MyComponent } from './MyComponent';

describe('MyComponent', () => {
  it('renders correctly', () => {
    render(<MyComponent data={mockData} />);
    expect(screen.getByText('Expected Text')).toBeInTheDocument();
  });
});

Accessibility

• Use semantic HTML
• Provide alt text for images
• Ensure keyboard navigation
• Use ARIA labels where needed
• Test with screen readers

Security

• Validate all inputs
• Sanitize user content
• Check permissions before actions
• Use parameterized queries
• Never expose secrets in client code

Next Steps

• Examples
• Extension Types