turbopack

Turbopack Best Practices

This document outlines best practices for developing with Turbopack, focusing on code organization, performance, security, testing, and tooling.

Project Tech Stack:

ALWAYS USE THE FOLLOWING IN CONJUNCTION WITH EACHOTHER TO HAVE A SAFE CODEBASE WHERE WE CAN MOVE FAST AND BREAK NOTHING

• Next.js
• Typescript + ESlint
• Zod + Prisma + tRPC + React Query
• Prisma (supabase) + Redis
• ShadCN + TailwindCSS v4
• Vitest Unit Tests

1. Core Principles

• Leverage the Turbo Engine: Turbopack's core strength lies in its Turbo engine for function-level caching. Understand and utilize this for incremental builds.
• Embrace Incremental Computation: Be mindful of how changes affect the build process. Design your application to maximize incremental computation benefits.
• Use TypeScript: Turbopack has built-in support for TypeScript and JSX, so use them to improve code quality and developer experience. Make full use of TypeScript's features like generics, interfaces and types.
• Follow Next.js Conventions: When using Turbopack within Next.js, adhere to Next.js's recommended patterns and practices.
• Avoid direct webpack configurations: Turbopack aims to abstract away webpack configurations, prefer using Next.js configurations to customize Turbopack.

2. Code Organization and Structure

• Directory Structure:
  • src/: All application source code should reside within the src/ directory.
  • components/: Reusable UI components.
  • pages/: (Next.js) Pages for routing.
  • api/: (Next.js) API routes.
  • lib/ or utils/: Utility functions and shared logic.
  • types/ or interfaces/: TypeScript type definitions and interfaces.
  • styles/ or css/: Global styles and CSS modules.
  • public/: Static assets (images, fonts, etc.).
• File Naming Conventions:
  • Use descriptive names for files and directories.
  • Component files: ComponentName.jsx or ComponentName.tsx.
  • Style files: ComponentName.module.css or ComponentName.module.scss.
  • Utility files: utilityName.js or utilityName.ts.
  • Consistent Case: Maintain a consistent casing convention (e.g., camelCase for variables, PascalCase for components). Use kebab-case for file names e.g. user-profile.tsx or user.router.ts
• Module Organization:
  • Group related code into modules with clear responsibilities.
  • Export only what is necessary from each module.
  • Use ES modules (import/export) for modularity.
• Component Architecture:
  • Atomic Design: Consider using Atomic Design principles to create a scalable and maintainable component architecture.
  • Composition: Favor composition over inheritance for component reusability.
  • Separation of Concerns: Separate UI logic, data fetching, and state management within components.
  • Keep components small: Focus on single responsability principle.
• Code Splitting Strategies:
  • Dynamic Imports: Use dynamic imports (import()) to split code into smaller chunks that are loaded on demand.
  • Route-Based Splitting: (Next.js) Each page in the pages/ directory is automatically code-split.
  • Component-Based Splitting: Split large components into smaller, lazily loaded sub-components.
  • Vendor Splitting: Turbopack automatically splits vendor code (third-party libraries) into separate chunks.