DOCSEARCHbyAlgolia
Submit Docs

Epic Stack Documentation

repository·main·Indexed 26 days ago

https://github.com/epicweb-dev/epic-stack

An opinionated project starter and reference implementation for shipping web applications to production. Built by Kent C. Dodds and contributors, it provides a stable foundation including a shadcn/ui component model, authentication flows, onboarding logic, and administrative tools for cache and profile management. Installable via the epicli command.

Tokens
61.1K
Snippets
158
Records
300
Agent score
90%

What's inside Epic Stack

  1. Overview of Epic Stack Authentication

    main

    The epic-auth skill provides a comprehensive implementation for user authentication within the Epic Stack. It covers session management, security protocols, and various authentication methods including traditional email/password, OAuth providers, and modern passwordless flows.

    Key capabilities include:

    • User authentication and session management via cookies.
    • OAuth provider integration (e.g., GitHub, Google).
    • Multi-factor authentication (2FA) using TOTP.
    • WebAuthn/Passkeys support.
    • Standard flows: Login, Signup, Logout, Email Verification, and Password Reset.

  2. Overview of Epic Stack: Forms

    main
    The epic-forms skill provides a comprehensive pattern for managing forms within an Epic Stack application. It integrates Conform for progressive enhancement and Zod for schema-based validation. This skill covers everything from basic setup to advanced requirements like file uploads, spam protection via honeypot fields, and handling complex data structures like fieldsets and arrays.

  3. Overview of Epic Stack features

    main

    The Epic Stack is a production-ready web development stack built on Remix. It includes features for deployment, database management, authentication, and testing. Key components include:

    • Framework & Deployment: Remix, Fly app deployment via Docker, and multi-region SQLite with LiteFS.
    • Database & ORM: SQLite with LiteFS and Prisma ORM.
    • Authentication: Email/Password with cookie-based sessions, Two-Factor Authentication (2FA) via authenticator apps, and Role-based User Permissions.
    • Email: Transactional email via Resend with password reset support.
    • Forms & Validation: Progressively enhanced, type-safe forms using Conform and runtime schema validation with Zod.
    • Styling & UI: Tailwind CSS, Radix UI component library, and built-in Light/Dark/System theme support.
    • Storage & Caching: Image storage via Tigris and caching via @epic-web/cachified (in-memory and SQLite-based).
    • Testing: End-to-end testing with Playwright, unit testing with Vitest and Testing Library (with a pre-configured Test Database), and local request mocking with MSW.
    • Observability & Tooling: Sentry for error monitoring, Grafana dashboards via Fly Metrics, ESLint, Prettier, and TypeScript.

  4. Understand the Epic Stack Permissions model

    main

    The Epic Stack uses a Role-Based Access Control (RBAC) model.

    • Roles: A user is assigned one or more roles.
    • Permissions: Each role contains a set of permissions.
    • Resolution: A user's effective permissions are the union of all permissions from all their assigned roles. If multiple roles provide the same permission, the most permissive version takes precedence.

    By default, the development seed provides fine-grained permissions using a action:resource:scope pattern (e.g., create:note:own or delete:user:any) and includes default user and admin roles.

  5. Authentication Strategy in Epic Stack

    main

    Epic Stack uses a hybrid authentication approach:

    1. Username/Password Authentication: Managed manually within the application logic rather than using a third-party library like remix-auth. This provides more control over the authentication flow.
    2. OAuth/Third-Party Authentication (e.g., GitHub): Uses remix-auth to handle external provider integrations.

  7. UI Component Architecture: shadcn/ui, Radix, and Tailwind

    main

    The Epic Stack uses a combination of three technologies to manage UI components:

    1. Radix UI: Provides the 'headless' primitive components that handle complex accessibility logic and component behavior.
    2. Tailwind CSS: Used for styling all components.
    3. shadcn/ui: Acts as a code registry rather than a traditional library. It provides pre-built component code (built on Radix and Tailwind) that you can copy, paste, and modify directly in your project.

    Because shadcn/ui components are part of your own source code, you have full control over customization. However, note that updates to these components are manual; there is no automated way to update them, which prevents breaking changes when you customize the code.

  8. Understand the image storage architecture

    main

    The Epic Stack uses a hybrid storage approach:

    1. Metadata: Relationships and ownership are stored in SQLite.
    2. Binary Data: The actual image files are stored in Tigris (S3-compatible storage).
    3. Serving: Image URLs point to your local server, which acts as a proxy to Tigris.

  9. Understand the ESM-first module system in the Epic Stack

    main

    The Epic Stack uses Native ECMAScript Modules (ESM) as its default module system. This aligns with modern JavaScript standards and the direction of frameworks like Remix v2.

    Key implications for developers:

    • No Synchronous Requires: Unlike CommonJS (CJS), you cannot use synchronous require() calls. If you need to load an ESM-only package from a CJS context, you must use dynamic import().
    • Module Resolution: Module resolution rules differ from CJS. Some packages may require you to import exports directly from specific file paths (e.g., import { ... } from 'package/dist/file.js') if they are not yet fully optimized for ESM resolution.
    • Package Compatibility: While most modern npm packages support ESM, you may occasionally encounter packages that require specific import patterns to work correctly within an ESM environment.

  10. Understand the SQLite architecture in Epic Stack

    main

    The Epic Stack uses SQLite as its primary database. Because SQLite stores the entire database in a single file on disk, it offers several architectural advantages and constraints:

    Advantages

    • Zero Latency: Being a local file reduces the 'n+1 problem' significantly.
    • Scalability: It can handle extremely large datasets (up to Exabyte scale).
    • Simplicity: Reduces operational complexity by eliminating the need for a separate database service, lowering both maintenance and running costs.

    Constraints & Workarounds

    • External Connections: Connecting from external clients is difficult because it is a local file. To manage data, you can run tools like prisma studio on the machine where the SQLite volume is mounted, or use the Dockerfile configuration to SSH into the SQLite CLI.
    • Real-time Features: SQLite does not support database subscriptions. Real-time use cases must be implemented using methods other than database subscriptions.
    • Enums: SQLite does not support native enums, so columns must use strings. Type enforcement for these strings can be handled via Prisma client extensions.
    • Multi-instance/Multi-region: Since SQLite is a local file, you cannot easily distribute it. For applications requiring multiple instances or multi-region support, use tools like Turso or LiteFS to manage distribution and read replica consistency.

  11. Session Management Strategy

    main
    The Epic Stack uses a database-backed session management strategy. Instead of relying solely on signed cookies (which cannot be proactively revoked), the stack uses a sessions table in the database to identify users. This allows for the capability to proactively invalidate sessions, such as implementing a "revoke all" feature for a user.

  12. Understand the Epic Stack Guiding Principles

    main

    The Epic Stack is designed around several core principles that influence its architecture and the way you should use it:

    • Limit Services: Favor building, deploying, and maintaining services yourself or running them within your app instance to reduce cost and complexity.
    • Include Only Most Common Use Cases: The starter app focuses on common patterns. For niche features or extensive examples, refer to the documentation rather than looking for them in the starter code.
    • Minimize Setup Friction: The stack aims to get apps to production quickly. It prioritizes services with free tiers for exploration and defers third-party signups until they are strictly necessary.
    • Optimize for Adaptability: The architecture is designed to allow you to swap between third-party services and custom-built services as product requirements change.
    • Only One Way: The stack avoids providing multiple ways to accomplish the same task in both code and documentation to prevent decision fatigue.
    • Offline Development: The stack strives to enable offline development by providing ways to mock third-party services (like email) for local environments.