heroku

---
description: Comprehensive best practices and coding standards for developing, deploying, and maintaining applications on the Heroku platform. This rule emphasizes the Twelve-Factor App methodology and provides detailed guidance for optimizing application architecture, performance, security, and maintainability on Heroku.
globs: **/*
---

- Follow the Twelve-Factor App methodology for building software-as-a-service applications.
  - **Codebase:** Maintain a single codebase tracked in version control (e.g., Git) for each application. Multiple deploys should be created from this single codebase.
  - **Dependencies:** Explicitly declare and isolate dependencies using a dependency management tool (e.g., `requirements.txt` for Python, `package.json` for Node.js, `Gemfile` for Ruby).
  - **Config:** Store configuration settings (database credentials, API keys, etc.) in environment variables. Avoid hardcoding configuration values in the application code.
  - **Backing Services:** Treat backing services (databases, message queues, caches) as attached resources accessed via URLs or connection strings.
  - **Build, Release, Run:** Strictly separate the build, release, and run stages. Build creates the executable, release combines the build with the config, and run executes the release in the execution environment.
  - **Processes:** Execute the application as one or more stateless processes. Persist data in backing services.
  - **Port Binding:** Export services via port binding. The application should be self-contained and listen for requests on a port.
  - **Concurrency:** Scale out via the process model. Use multiple processes to handle concurrency.
  - **Disposability:** Maximize robustness with fast startup and graceful shutdown.
  - **Dev/Prod Parity:** Keep development, staging, and production environments as similar as possible.
  - **Logs:** Treat logs as event streams. Write logs to standard output, and let the platform handle aggregation.
  - **Admin Processes:** Run admin/management tasks as one-off processes.

- **Code Organization and Structure:**
  - **Directory Structure:** Organize your project with a clear directory structure. Examples:
    - `/`: Project root
    - `/app`: Application source code
    - `/config`: Configuration files
    - `/tests`: Unit and integration tests
    - `/scripts`: Deployment and maintenance scripts
    - `/docs`: Documentation
  - **File Naming Conventions:** Use descriptive and consistent file names (e.g., `user_model.py`, `user_controller.js`).
  - **Module Organization:** Break down your application into modular components with well-defined interfaces.
  - **Component Architecture:** Use a component-based architecture to promote code reuse and maintainability. Consider using frameworks like React, Angular, or Vue.js for front-end development.
  - **Code Splitting:** Implement code splitting to reduce initial load times.  Load modules on demand.

- **Common Patterns and Anti-patterns:**
  - **Design Patterns:** Use established design patterns (e.g., MVC, Observer, Factory) to structure your code.
  - **Recommended Approaches:** Use environment variables for configuration, stateless processes, and logging to stdout.
  - **Anti-patterns:** Avoid hardcoding configuration values, sticky sessions, and relying on local file storage for persistent data.
  - **State Management:** Choose a state management solution appropriate for your application (e.g., Redux, Vuex, Context API) to handle global application state.
  - **Error Handling:** Implement robust error handling with try-except blocks and logging of exceptions. Use a centralized error reporting system (e.g., Sentry, Rollbar) to track errors in production.

- **Performance Considerations:**
  - **Optimization Techniques:** Use caching (e.g., Redis, Memcached) to reduce database load. Optimize database queries. Use asynchronous tasks for long-running operations.
  - **Memory Management:** Avoid memory leaks by properly managing resources. Use garbage collection tools to identify and fix memory issues.
  - **Rendering Optimization:** Optimize front-end rendering by minimizing DOM manipulations and using techniques like virtual DOM.
  - **Bundle Size Optimization:** Reduce bundle size by minifying code, removing unused code, and using tree shaking.
  - **Lazy Loading:** Implement lazy loading for images, modules, and other resources to improve initial load times.

- **Security Best Practices:**
  - **Common Vulnerabilities:** Prevent common vulnerabilities like SQL injection, cross-site scripting (XSS), and cross-site request forgery (CSRF).
  - **Input Validation:** Validate all user inputs to prevent malicious data from entering your application.
  - **Authentication and Authorization:** Implement secure authentication and authorization mechanisms (e.g., OAuth, JWT). Use HTTPS to encrypt all communication.
  - **Data Protection:** Encrypt sensitive data at rest and in transit. Use strong passwords and secure password storage.
  - **Secure API Communication:** Validate API requests, use rate limiting to prevent abuse, and secure API keys.

- **Testing Approaches:**
  - **Unit Testing:** Write unit tests for individual components to ensure they function correctly.
  - **Integration Testing:** Write integration tests to verify the interaction between different components.
  - **End-to-end Testing:** Write end-to-end tests to simulate user interactions and verify the application as a whole.
  - **Test Organization:** Organize your tests in a clear and maintainable structure. Use test runners like Jest, Mocha, or pytest.
  - **Mocking and Stubbing:** Use mocking and stubbing to isolate components during testing.

- **Common Pitfalls and Gotchas:**
  - **Frequent Mistakes:** Forgetting to configure environment variables, deploying code without testing, and not handling errors properly.
  - **Edge Cases:** Be aware of edge cases like slow network connections, unexpected user inputs, and resource limitations.
  - **Version-Specific Issues:** Check for version-specific issues in the Heroku documentation and release notes.
  - **Compatibility Concerns:** Ensure compatibility between Heroku and the technologies you are using (e.g., language versions, database drivers).
  - **Debugging Strategies:** Use logging, debugging tools (e.g., Heroku logs, remote debugging), and error reporting systems to diagnose issues.

- **Tooling and Environment:**
  - **Recommended Development Tools:** Use a code editor like VS Code or Sublime Text, a version control system like Git, and a dependency management tool appropriate for your language.
  - **Build Configuration:** Configure your build process using buildpacks or Dockerfiles.
  - **Linting and Formatting:** Use linters and formatters (e.g., ESLint, Prettier) to enforce code style and catch errors.
  - **Deployment Best Practices:** Use Heroku CLI for deployment. Automate deployments using CI/CD.
  - **CI/CD Integration:** Integrate your application with a CI/CD pipeline (e.g., GitHub Actions, CircleCI, Travis CI) for automated testing and deployment.

- **Specific Heroku Considerations**
  - **Dynos:** Understand the different types of dynos available on Heroku and choose the appropriate dyno type for your application.
  - **Buildpacks:** Use buildpacks to automatically configure your application's environment on Heroku. You can also create custom buildpacks.
  - **Add-ons:** Use Heroku add-ons to easily integrate third-party services into your application (e.g., databases, caching, logging).
  - **Heroku CLI:** Familiarize yourself with the Heroku CLI for managing your applications, databases and deployments.
  - **Procfile:** Use a Procfile to define the processes that run in your application. This typically includes web, worker, and other processes.

- **Continuous Integration/Continuous Deployment (CI/CD)**
  - Implement a robust CI/CD pipeline for automated testing and deployment.
  - Use tools like GitHub Actions, CircleCI, or Jenkins to automate the build, test, and deploy processes.
  - Configure automated testing to run on every code commit.
  - Implement automated deployment to staging and production environments.
  - Use feature flags to enable continuous deployment without breaking changes to production code.

- **Monitoring and Logging**
  - Use Heroku's built-in logging capabilities to monitor application performance and identify errors.
  - Integrate with third-party logging services like Sumo Logic, Datadog, or New Relic for advanced monitoring and analytics.
  - Set up alerts for critical errors and performance issues.
  - Use log aggregation tools to centralize and analyze logs from multiple dynos.

- **Scaling and Performance**
  - Monitor application performance metrics to identify bottlenecks.
  - Scale dynos horizontally to handle increased traffic.
  - Use caching strategies to reduce database load and improve response times.
  - Optimize database queries and indexes.
  - Implement load balancing to distribute traffic across multiple dynos.

- **Security Hardening**
  - Implement robust security measures to protect against common web vulnerabilities.
  - Use HTTPS to encrypt all communication between clients and the server.
  - Implement proper input validation and output encoding to prevent XSS and SQL injection attacks.
  - Use a Content Security Policy (CSP) to restrict the sources of content that can be loaded by the browser.
  - Protect against CSRF attacks by implementing CSRF tokens.
  - Regularly update dependencies to patch security vulnerabilities.
  - Conduct regular security audits to identify and address potential security weaknesses.

- **Database Management**
  - Choose the appropriate database for your application's needs (e.g., PostgreSQL, MySQL, MongoDB).
  - Use database connection pooling to improve performance.
  - Optimize database queries and indexes.
  - Implement database backups and recovery strategies.
  - Use database migrations to manage schema changes.
  - Secure database credentials and access.

By adhering to these best practices, developers can build and maintain robust, scalable, and secure applications on the Heroku platform.