create-farcaster-mini-app/FORMATTING.md

Formatting and Code Style Guide

This project uses a comprehensive set of tools to ensure consistent code formatting and quality across the entire codebase.

Tools Configured

🎨 Prettier - Code Formatter

• Automatically formats JavaScript, TypeScript, CSS, JSON, and Markdown files
• Configuration: .prettierrc
• Ignore patterns: .prettierignore

🔍 ESLint - Linter and Code Quality

• Enforces code quality rules and catches potential bugs
• Configuration: .eslintrc.json
• Ignore patterns: .eslintignore

⚙️ EditorConfig - Cross-Editor Consistency

• Ensures consistent indentation and line endings across different editors
• Configuration: .editorconfig

🔧 VS Code Settings

• Pre-configured workspace settings for optimal development experience
• Configuration: .vscode/settings.json
• Recommended extensions: .vscode/extensions.json

Quick Start

Installation

When you create a new project using this template, all formatting tools are already configured. Simply run:

npm install

Available Scripts

Formatting

npm run format          # Format all files with Prettier
npm run format:check    # Check if files are properly formatted
npm run format:fix      # Format files and fix ESLint issues

Linting

npm run lint           # Run ESLint
npm run lint:fix       # Run ESLint and auto-fix issues
npm run lint:check     # Run ESLint with zero warnings tolerance

Type Checking

npm run type-check     # Run TypeScript compiler without emitting files

Combined Checks

npm run check          # Run type-check, lint:check, and format:check

Editor Setup

VS Code (Recommended)

1. Install recommended extensions when prompted
2. Formatting and linting will work automatically on save
3. Key extensions:
   • Prettier: Code formatter
   • ESLint: Linting and error detection
   • EditorConfig: Consistent editor settings

Other Editors

• WebStorm/IntelliJ: Built-in support for Prettier and ESLint
• Vim/Neovim: Use appropriate plugins for Prettier and ESLint
• Emacs: Configure with prettier-js and flycheck-eslint

Configuration Details

Prettier Configuration (.prettierrc)

{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false,
  "bracketSpacing": true,
  "bracketSameLine": false,
  "arrowParens": "avoid",
  "endOfLine": "lf"
}

Key ESLint Rules

• TypeScript and React best practices
• Prettier integration (no conflicts)
• Async/await safety rules
• Import organization
• Console warnings (allows warn/error)

EditorConfig Settings

• 2-space indentation for most files
• LF line endings
• UTF-8 encoding
• Trim trailing whitespace
• Insert final newline

Git Hooks (Optional)

You can set up pre-commit hooks using husky and lint-staged:

npm install --save-dev husky lint-staged
npx husky install
npx husky add .husky/pre-commit "npx lint-staged"

The project includes a .lintstagedrc configuration that will:

• Run ESLint and Prettier on staged JS/TS files
• Run Prettier on staged JSON, CSS, and Markdown files

Team Guidelines

Before Committing

1. Run npm run check to ensure code quality
2. Fix any linting errors or formatting issues
3. Commit your changes

Pull Request Requirements

• All checks must pass
• Code must be properly formatted
• No ESLint warnings or errors
• TypeScript compilation must succeed

Customization

If you need to modify the formatting rules:

1. Prettier: Edit .prettierrc
2. ESLint: Edit .eslintrc.json
3. EditorConfig: Edit .editorconfig

Remember to discuss any changes with your team first!

Troubleshooting

Common Issues

"Prettier and ESLint conflict"

• This shouldn't happen as we use eslint-config-prettier
• If it does, check that Prettier rules come last in ESLint extends

"Format on save not working"

• Ensure Prettier extension is installed and enabled
• Check VS Code settings for editor.formatOnSave: true
• Verify the file type is in ESLint validation array

"TypeScript errors in JavaScript files"

• Check file extension (.js vs .ts)
• Verify ESLint overrides for JavaScript files

"Formatting different in CI vs local"

• Ensure same Node.js version
• Check line ending settings (LF vs CRLF)
• Verify Prettier version consistency

Getting Help

• Check the documentation for Prettier
• Check the documentation for ESLint
• Review Next.js ESLint configuration

Best Practices

File Organization

• Keep configuration files in project root
• Use meaningful names for custom ESLint rules
• Group related imports together

Code Style

• Use meaningful variable names
• Prefer const over let when possible
• Use template literals for string interpolation
• Keep functions small and focused
• Add JSDoc comments for complex functions

React Specific

• Use functional components with hooks
• Prefer explicit prop types (TypeScript interfaces)
• Use meaningful component names
• Keep components focused on single responsibility

TypeScript

• Enable strict mode
• Use proper types instead of any
• Leverage type inference where appropriate
• Use proper generic constraints

---

This formatting guide is automatically included with every new project created from this template.