Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

3.4 KB
Raw Blame
---
description: Rules for writing frontend code at PostHog (mostly React + Typescript with Kea)
globs: frontend/**/*.ts,frontend/**/*.tsx,products/**/*.ts,products/**/*.tsx
alwaysApply: false
---

You are an expert in TypeScript, React, Kea, Tailwind, and UX design.

Since you are an expert, remember that when you add or remove anything in a kea *logic.ts file there will always be typescript errors.

You need to wait for the kea typegen to complete before those errors go away, please don't start editing files trying to fix the errors until kea typegen has run

Also, any file with a name ending logicType.ts is autogenerated and should never be edited

Architecture
  - Two-layer system: Kea (data/state) -> React (view/template)
  - Always implement data layer in Kea logic; avoid React state

Code Style and Structure
  - Write TypeScript with proper typing for all new code
  - Use functional programming patterns; avoid classes
  - Prefer iteration and modularization over code duplication.
  - Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
  - Don't use `useState` or `useEffect` to store local state. It's false convenience. Take the extra 3 minutes and change it to a `logic` early on in the development.
  - Logics still have a tiny initialization cost. Hence this rule doesn't apply to library components in the `lib/` folder, which might be rendered hundreds of times on a page with different sets of data. Still feel free to write a logic for a complicated `lib/` component when needed.
  - Use named exports; avoid default exports
  - Structure files logically: logic, component, types, styles

Naming Conventions
  - Always look around the codebase for naming conventions, and follow the best practices of the environment (e.g. use `camelCase` variables in JS, `snake_case` in Python).
  - Use clear, yet functional names (`searchResults` vs `data`).
  - Logics are camelCase (`dashboardLogic`)
  - React components are PascalCase (`DashboardMenu`).
  - Props for both logics and components are PascalCase and end with `Props` (`DashboardLogicProps` & `DashboardMenuProps`)
  - Name the `.ts` file according to its main export: `DashboardMenu.ts` or `DashboardMenu.tsx` or `dashboardLogic.ts` or `Dashboard.scss`. Pay attention to the case.
  - Avoid `index.ts`, `styles.css`, and other generic names, even if this is the only file in a directory.

UI and Styling
  - Use Tailwind CSS as primary styling solution
  - For non-Tailwind cases:
    - Use SCSS with component-specific files
    - Namespace under component class (.DashboardMenu)
    - Follow BEM for modals (.DashboardMenu__modal)
    - Import styles directly (MyComponent.scss)
  - Replace custom SCSS with Tailwind when possible
  - When mentioning PostHog products, the product names should use Sentence casing, not Title Casing. For example, 'Product analytics', not 'Product Analytics'. Any other buttons, tab text, tooltips, etc should also all use Sentence casing. For example, 'Save as view' instead of 'Save As View'.

Testing Requirements
  - Logic tests for all Kea logic files
  - React Testing Library tests for interactive lib/ components
  - Add presentational elements to Storybook
  - Run storybook locally: pnpm storybook

Core Principles
  - Prioritize maintainability over development speed
  - Keep data layer separate from view hierarchy
  - Write clear, understandable code
  - Think data first, implement views second