# The Epic Stack: a Remix-based starter that ships opinions with the code

> The Epic Stack is an opinionated full stack starter built on React Router and Prisma, maintained by Kent C. Dodds and contributors. It is for teams who would rather inherit decisions than debate them.

**epicweb-dev/epic-stack** — This is a Full Stack app starter with the foundational things setup and configured for you to hit the ground running on your next EPIC idea.

- Repository: https://github.com/epicweb-dev/epic-stack
- Website: https://www.epicweb.dev/epic-stack
- Stars: 5,539 · Forks: 464
- Language: TypeScript
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/epicweb-dev-epic-stack

## What the Epic Stack actually decides for you

The README describes the project as an "opinionated project starter and reference" that lets teams "ship their ideas to production faster and on a more stable foundation". The word opinionated is doing real work there. This is not a component library or a set of utilities you adopt piecemeal. It is a whole application skeleton with authentication, a database layer, caching, testing and deployment configuration already wired together, and the value comes from the wiring rather than from any single dependency.

The intended audience is a team starting a new product who would otherwise spend the first two weeks arguing about session storage, form validation, migration tooling and end-to-end test runners. Kent C. Dodds and contributors made those calls once, and the repository carries the result. Teams that already have strong house conventions will find less to like, because the starter's decisions are not modular. Replacing the authentication approach means touching routes, session handling and the Prisma schema together, not swapping one package for another.

The package name in package.json is epic-stack-template, which is a useful reminder of what you are actually cloning: a template, not a framework. Once you initialize it, the code is yours and upstream changes are not automatically yours.

## How the pieces fit: React Router, Prisma and a mockable server

The repository is a TypeScript application with app/, server/, prisma/ and tests/ at the top level, plus a single index.ts that the dev and start scripts execute directly. That entry point is worth noting: the scripts run node index.ts, so the server bootstrap is a file you can read rather than a hidden CLI.

Routing comes from React Router. The build script is react-router build, the typecheck script runs react-router typegen before tsc, and react-router.config.ts sits at the repository root. A release note dated 2025-10-16 is titled "Migrate to react-router-auto-routes", so the route conventions follow that package rather than the older flat-file layout. Data persistence is Prisma: the prisma/ directory holds the schema, and the setup script runs prisma migrate deploy followed by prisma generate --sql.

Caching and cross-cutting concerns come from the @epic-web scope, which appears repeatedly in dependencies: @epic-web/cachified for caching, @epic-web/client-hints, @epic-web/totp for time-based one-time passwords, and @epic-web/invariant. Form handling is @conform-to/react with @conform-to/zod, so validation schemas are shared between client and server. The MOCKS environment variable is the other structural idea. The dev script sets MOCKS=true, and .env.example notes that the mocks and some code rely on the GitHub variables being prefixed with MOCK_, otherwise "the real github api will be attempted". That gives you a development loop that does not require live third-party credentials.

## Installing the Epic Stack and running it for the first time

The README gives exactly one command for getting started. It scaffolds a new project from the template rather than installing a runtime dependency.

```bash
npx epicli
```

After the initializer finishes and dependencies are installed, the repository provides a setup script that builds the app, applies migrations, generates the Prisma client and installs Playwright browsers. Run it before the first dev server start, otherwise the database and browser binaries will be missing.

```bash
npm run setup
```

The environment file is the next thing to look at. .env.example lists the keys the app reads, including SESSION_SECRET, HONEYPOT_SECRET, RESEND_API_KEY, SENTRY_DSN and the GitHub OAuth trio. Copy it to .env and fill in values before starting. Note the comment on ALLOW_INDEXING: setting it to false prevents search engines from indexing the site.

```bash
cp .env.example .env
npm run dev
```

The dev script runs with MOCKS=true, so the GitHub variables can keep their MOCK_ prefixes and the app will use mock data instead of calling the real API. To run against real services, use the alternate script.

```bash
npm run dev:no-mocks
```

Before opening a pull request or deploying, the validate script runs the unit tests, lint, typecheck and the end-to-end suite together via run-p, which is the closest thing the repository has to a single definition of green.

## The cost of inheriting someone else's opinions

The main limitation is the one the README advertises. An opinionated starter is only cheap if you agree with the opinions, and the Epic Stack's opinions run deep enough that disagreement is expensive. The authentication flow, the session model, the TOTP support, the caching layer and the form validation approach are all interconnected through @epic-web packages. A team that wants a different session strategy is not changing a config value; it is rewriting the routes and the server code that depend on it.

There is also an upgrade question the repository does not resolve for you. Because npx epicli produces a copy rather than a dependency, there is no version to bump. The release notes show the project itself moving: Tailwind v4 in April 2025, react-router-auto-routes in October 2025, and a January 2026 release covering Prisma 6, native TypeScript and skills. Each of those is a migration you would perform by hand against your own diverged codebase. The README does not document a supported upgrade path for scaffolded projects, and the docs directory is the place to check whether one exists before you commit.

The stack is also wrong for a small static site, a content-heavy marketing page, or anything where a database and authentication are overhead rather than requirements. It carries Playwright, Prisma, Sentry and a deployment configuration; a project that needs none of those is paying for them anyway.

## Epic Stack compared with a plain React Router project

The honest alternative is not another starter. It is starting from the React Router template or a bare Vite project and adding only what you need. The difference in approach is where the decisions live. With a bare project, every choice is made at the moment you need it, and each one is small. With the Epic Stack, all of them were made up front by someone else, and you inherit the whole set at once.

That trade is visible in the file layout. A bare React Router app has a router config and an app directory. This repository adds prisma/, tests/, server/, a fly.toml for deployment, a playwright.config.ts, an eslint.config.js, a components.json for the UI component setup, and a docs/ directory that the README points to with the instruction to read it. Each of those is a decision you did not have to make and now have to maintain.

If your team's bottleneck is genuinely decision fatigue on a greenfield product, the trade favors the Epic Stack. If your bottleneck is fitting into an existing platform team's conventions, or if you already know exactly which auth and ORM you want, the bare template is faster because you skip the untangling.

## Maintenance, licensing and what to check before you commit

The repository is not archived, and the last push was on 2026-08-29, which is recent. The release cadence shown in the notes is roughly every few months, with entries in April 2025, October 2025 and January 2026, so the project is being revised rather than frozen. That cuts both ways: active revision means the starter stays current with React Router and Prisma, and it also means scaffolded copies drift from upstream quickly.

The licence is MIT, declared in both the repository metadata and package.json, with LICENSE.md at the root. MIT is permissive, so a scaffolded application can be used commercially and modified freely. The dependencies carry their own licences, and nothing in the repository's own documentation reviews those, so a team with licence review requirements should audit the dependency tree themselves rather than assuming the root licence covers everything.

Deployment is partly pre-answered. fly.toml exists at the root, and .env.example includes LITEFS_DIR and DATABASE_PATH along with Tigris object storage keys (AWS_ENDPOINT_URL_S3, BUCKET_NAME, AWS_REGION), which points at a Fly.io-shaped deployment with SQLite and S3-compatible storage. If you are deploying elsewhere, that configuration is a starting point to rewrite, not a portable default.

## Conclusion

Adopt the Epic Stack when your team wants a working baseline for auth, database, testing and deployment rather than a blank React Router project, and when you accept that the starter's opinions are the product. Do not adopt it if you need a stack that stays out of the way of your own conventions, or if your team cannot review a large init template before merging it. Before committing, read the docs directory, run npm run validate once, and check the react-router.config.ts and fly.toml files to confirm the router and deployment choices match your environment.

## FAQ

### What is the Epic Stack?

It is an opinionated full stack starter and reference for TypeScript web apps, built on React Router and Prisma, maintained by Kent C. Dodds and contributors. The README describes its purpose as letting teams ship to production faster on a more stable foundation.

### What is Epic's tech stack?

The Epic Stack uses TypeScript with React Router for routing and building, Prisma for the database layer and migrations, Conform with Zod for form validation, and Playwright plus Vitest for testing. It also depends on several @epic-web packages for caching, client hints and TOTP.

### How do I install the Epic Stack?

The README gives a single command, npx epicli, which scaffolds a new project from the template. After dependencies are installed, run npm run setup to build the app, apply Prisma migrations, generate the client and install Playwright browsers.

### Does the Epic Stack support a mock mode for development?

Yes. The dev script sets MOCKS=true, and .env.example notes that the mocks and some code rely on the GitHub variables being prefixed with MOCK_, otherwise the real GitHub API will be attempted. Use npm run dev:no-mocks to run against real services.

### What licence does the Epic Stack use?

The repository metadata and package.json both declare MIT, and LICENSE.md sits at the repository root. Dependencies carry their own licences, which the repository's documentation does not review.

## Sources

- [epicweb-dev/epic-stack on GitHub](https://github.com/epicweb-dev/epic-stack)
- [License: MIT](https://github.com/epicweb-dev/epic-stack/blob/main/LICENSE)
- [Project website](https://www.epicweb.dev/epic-stack)
- [README](https://github.com/epicweb-dev/epic-stack/blob/main/README.md)
- [Releases](https://github.com/epicweb-dev/epic-stack/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/epicweb-dev-epic-stack