Best Practices
Guidelines and recommendations for developing, testing, and maintaining the Makinari platform.
Code Organization
Keep files under 500 lines
Maintain readability and manageability by keeping individual files concise.
Split large components into smaller, focused modules.Use ES Modules consistently
Import/export syntax should be consistent across the project.
import { Component } from './Component' instead of require()Follow TypeScript best practices
Use proper typing, interfaces, and avoid any types.
interface User { id: string; name: string; }Testing
Write comprehensive tests
Use Jest for unit tests and React Testing Library for component tests.
test('renders user data correctly', () => { ... })Test edge cases and error states
Ensure your code handles unexpected inputs gracefully.
Test with null, undefined, empty strings, and invalid data.Maintain high test coverage
Aim for at least 80% code coverage on critical paths.
Use coverage reports to identify untested code.Git Workflow
Use descriptive commit messages
Write clear, concise commit messages that explain what changed.
feat: add user authentication with magic linksCreate feature branches
Work on features in separate branches before merging.
git checkout -b feature/user-dashboardReview code before merging
Use pull requests to review code changes.
Create PRs for all changes, even small ones.Security
Never commit secrets
Use environment variables for sensitive data.
process.env.STRIPE_SECRET_KEY instead of hardcoded keysValidate all inputs
Use Zod or similar libraries to validate user inputs.
const schema = z.object({ email: z.string().email() })Use HTTPS in production
Ensure all communications are encrypted.
Configure SSL certificates and redirect HTTP to HTTPSDocumentation
Write clear README files
Include setup instructions, API documentation, and examples.
Document installation, configuration, and usage steps.Comment complex logic
Explain why, not what, in your code comments.
// Using debounce to prevent excessive API callsKeep documentation updated
Update docs when code changes.
Review and update README files with each release.Performance
Optimize bundle size
Use dynamic imports and code splitting.
const Component = lazy(() => import('./Component'))Implement proper caching
Cache API responses and static assets appropriately.
Use React Query for server state managementMonitor performance metrics
Track Core Web Vitals and other performance indicators.
Use tools like Lighthouse and Web VitalsCommon Anti-Patterns to Avoid
Avoid large, monolithic components
Components should have a single responsibility.
❌ 500+ line component with multiple concerns✅ Split into smaller, focused componentsDon't use any types in TypeScript
Defeats the purpose of using TypeScript.
❌ const data: any = fetchData()✅ const data: UserData = fetchData()Avoid inline styles and hardcoded values
Use CSS classes and design tokens instead.
❌ style={{ color: '#3ECF8E', fontSize: '16px' }}✅ className='text-accent text-base'Don't ignore error handling
Always handle potential errors gracefully.
❌ fetch(url).then(data => processData(data))✅ fetch(url).then(data => processData(data)).catch(handleError)