# Applifting Frontend Playbook

> Opinionated guidelines for frontend projects at Applifting — a handbook of battle-tested patterns and conventions for writing React code, structuring applications, and maintaining consistency across projects.

## Table of contents

- [Introduction](/frontend-playbook/getting-started/introduction.md): Overview of the Applifting Frontend Playbook — a handbook for consistent React code and project structure.
- [General Principles](/frontend-playbook/getting-started/general-principles.md): Core principles: clean code, DRY, separation of concerns, minimal side effects, and error handling.
- [Feature-sliced Design Overview](/frontend-playbook/project-structure/feature-sliced-design-overview.md): Introduction to Feature-sliced Design based on Bulletproof React for scalable project structure.
- [Pages & Routes (Common Concepts)](/frontend-playbook/project-structure/pages-routes.md): Common concepts for pages and routes: composition, layout, headings, and feature integration.
- [Next.js Structure](/frontend-playbook/project-structure/nextjs-structure.md): Recommended Next.js project structure using App Router with feature-sliced design principles.
- [TanStack Router (or React Router)](/frontend-playbook/project-structure/tanstack-router-structure.md): Project structure for TanStack Router apps with file-based routing and feature-sliced design.
- [Cross-Feature Composition (Escape Hatch)](/frontend-playbook/project-structure/cross-feature-composition.md): Escape hatch pattern for injecting components across feature boundaries via page-level context.
- [File Naming](/frontend-playbook/naming-conventions/file-naming.md): File naming conventions: PascalCase for components, camelCase for hooks and other files.
- [Variable Naming](/frontend-playbook/naming-conventions/variable-naming.md): Variable naming conventions: PascalCase for types, camelCase for variables, and boolean prefixes.
- [Function Naming](/frontend-playbook/naming-conventions/function-naming.md): Naming functions with the A/HC/LC pattern: action + high context + low context for clarity.
- [Naming Tips & Gotchas](/frontend-playbook/naming-conventions/naming-tips.md): Common naming pitfalls and tips for TypeScript types, zod schemas, and avoiding unnecessary prefixes.
- [Writing Components](/frontend-playbook/components/writing-components.md): Guidelines for writing React components: props definition, destructuring, arrow functions, and avoiding FC types.
- [Code Order in Components](/frontend-playbook/components/code-order.md): Recommended order of code inside React components: state, derived values, handlers, then effects.
- [Compound Component Pattern](/frontend-playbook/components/compound-components.md): The compound component pattern for flexible, declarative APIs with implicit state sharing.
- [Type vs Interface](/frontend-playbook/typescript/type-vs-interface.md): Why we default to 'type' over 'interface' in TypeScript: unions, mapped types, and declaration merging.
- [Utility Types](/frontend-playbook/typescript/utility-types.md): Leveraging TypeScript utility types like Pick, Omit, Exclude, Extract, and ReturnType.
- [Immutability](/frontend-playbook/typescript/immutability.md): Using 'as const' and 'satisfies' for immutable, type-safe values in TypeScript.
- [Enumerations](/frontend-playbook/typescript/enumerations.md): Avoiding native TypeScript enums in favor of string literal unions or const objects.
- [Type Guards and Parsing Data](/frontend-playbook/typescript/typeguards.md): Using type guards and runtime validation with zod or narrowland for type-safe data handling.
- [Function Best Practices](/frontend-playbook/coding-patterns/function-best-practices.md): Function guidelines: arrow functions, async/await, single responsibility, and avoiding boolean flags.
- [Pure Functions](/frontend-playbook/coding-patterns/pure-functions.md): Writing pure functions for better testability and performance. Define them outside components when possible.
- [Boolean Conversion](/frontend-playbook/coding-patterns/boolean-conversion.md): How to properly convert values to booleans using !! or Boolean(), with type narrowing considerations.
- [Declarative vs Imperative](/frontend-playbook/coding-patterns/declarative-vs-imperative.md): Why declarative code is preferred over imperative: clearer intent with filter, map, and other array methods.
- [Environment Variables](/frontend-playbook/tooling/environment-variables.md): Managing environment variables with T3 Env for validation and type-safety across frameworks.
- [Code Comments](/frontend-playbook/tooling/code-comments.md): Comment formatting guidelines using TODO, FIXME, and NOTE prefixes for better code clarity.
- [UI Components (Shadcn)](/frontend-playbook/ui-styling/ui-components.md): Using Shadcn/ui for reusable UI components built on Radix primitives with Tailwind styling.
- [Tailwind CSS](/frontend-playbook/ui-styling/tailwind-css.md): Tailwind CSS best practices: cn utility, theming with CSS variables, and managing color palettes.
- [Assets & Icons](/frontend-playbook/ui-styling/assets-icons.md): Best practices for optimizing images, SVGs, and using icon libraries in React projects.
- [Semantic HTML](/frontend-playbook/html-accessibility/semantic-html.md): Use HTML elements for their intended purpose. Better accessibility, SEO, and maintainability with minimal effort.
- [Accessibility Basics](/frontend-playbook/html-accessibility/accessibility.md): Essential accessibility practices that cover 80% of common issues. Focus on keyboard navigation, images, forms, and color.
- [TanStack Query Overview](/frontend-playbook/data-fetching/tanstack-query-overview.md): Why TanStack Query is our go-to for REST and GraphQL. Includes Apollo Client comparison and zod validation patterns.
- [HTTP Client with ky](/frontend-playbook/data-fetching/http-client-ky.md): Using ky HTTP client with custom hooks, authentication handling, and automatic token refresh.
- [Query Keys & Options](/frontend-playbook/data-fetching/query-keys-options.md): Patterns for query key factories and queryOptions to keep data fetching flexible and maintainable.
- [API Type Generators](/frontend-playbook/data-fetching/api-type-generators.md): Recommended tools for generating TypeScript types from GraphQL schemas and OpenAPI specifications.
- [Router Choice](/frontend-playbook/routing/router-choice.md): Why we recommend TanStack Router over React Router for better typesafety and ecosystem integration.
- [TanStack Router Patterns](/frontend-playbook/routing/tanstack-router-patterns.md): Integrating TanStack Router with TanStack Query: loaders, prefetching, suspense boundaries, and pending states.
- [Forms](/frontend-playbook/forms-translations/forms.md): Our recommended form stack: react-hook-form with zod validation and Shadcn/ui form components.
- [Translations](/frontend-playbook/forms-translations/translations.md): Setting up i18n with react-i18next or next-intl. Covers namespaces, hooks usage, and nested translation keys.
- [Git Workflow](/frontend-playbook/contributing/git-workflow.md): Git workflow standards: branch naming, commit messages following conventional commits, and JIRA integration.
- [Merge Requests](/frontend-playbook/contributing/merge-requests.md): Merge request conventions: naming, squashing commits, review process, and conventional comments format.