chore: migrate bootstrap and package management to pnpm

.env.example

@@ -1,6 +1,9 @@
 LITEFS_DIR="/litefs/data"
+# DATABASE_PATH is a filesystem path used by LiteFS/sqlite3 helpers.
 DATABASE_PATH="./prisma/data.db"
-DATABASE_URL="file:./data.db?connection_limit=1"
+# DATABASE_URL is Prisma's SQLite connection string and must keep the file: prefix.
+# Under Prisma 7 config, keep it rooted at the repo so it resolves to prisma/data.db.
+DATABASE_URL="file:./prisma/data.db?connection_limit=1"
 CACHE_DATABASE_PATH="./other/cache.db"
 SESSION_SECRET="super-duper-s3cret"
 HONEYPOT_SECRET="super-duper-s3cret"

.github/workflows/deploy.yml

@@ -22,22 +22,28 @@ jobs:
       - name: ⬇️ Checkout repo
         uses: actions/checkout@v4
 
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11.1.2
+
       - name: ⎔ Setup node
         uses: actions/setup-node@v4
         with:
           node-version: 22
+          cache: pnpm
 
-      - name: 📥 Download deps
-        uses: bahmutov/npm-install@v1
+      - name: 📥 Install deps
+        run: pnpm install --frozen-lockfile
 
       - name: 🏄 Copy test env vars
         run: cp .env.example .env
 
       - name: 🛠 Setup Database
-        run: npx prisma migrate deploy && npx prisma generate --sql
+        run: pnpm exec prisma migrate deploy && pnpm exec prisma generate --sql
 
       - name: 🔬 Lint
-        run: npm run lint
+        run: pnpm run lint
 
   typecheck:
     name: ʦ TypeScript
@@ -46,25 +52,31 @@ jobs:
       - name: ⬇️ Checkout repo
         uses: actions/checkout@v4
 
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11.1.2
+
       - name: ⎔ Setup node
         uses: actions/setup-node@v4
         with:
           node-version: 22
+          cache: pnpm
 
-      - name: 📥 Download deps
-        uses: bahmutov/npm-install@v1
-
-      - name: 🏗 Build
-        run: npm run build
+      - name: 📥 Install deps
+        run: pnpm install --frozen-lockfile
 
       - name: 🏄 Copy test env vars
         run: cp .env.example .env
 
       - name: 🛠 Setup Database
-        run: npx prisma migrate deploy && npx prisma generate --sql
+        run: pnpm exec prisma migrate deploy && pnpm exec prisma generate --sql
+
+      - name: 🏗 Build
+        run: pnpm run build
 
       - name: 🔎 Type check
-        run: npm run typecheck --if-present
+        run: pnpm run typecheck
 
   vitest:
     name: ⚡ Vitest
@@ -73,22 +85,28 @@ jobs:
       - name: ⬇️ Checkout repo
         uses: actions/checkout@v4
 
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11.1.2
+
       - name: ⎔ Setup node
         uses: actions/setup-node@v4
         with:
           node-version: 22
+          cache: pnpm
 
-      - name: 📥 Download deps
-        uses: bahmutov/npm-install@v1
+      - name: 📥 Install deps
+        run: pnpm install --frozen-lockfile
 
       - name: 🏄 Copy test env vars
         run: cp .env.example .env
 
       - name: 🛠 Setup Database
-        run: npx prisma migrate deploy && npx prisma generate --sql
+        run: pnpm exec prisma migrate deploy && pnpm exec prisma generate --sql
 
       - name: ⚡ Run vitest
-        run: npm run test -- --coverage
+        run: pnpm run test -- --coverage
 
   playwright:
     name: 🎭 Playwright
@@ -101,19 +119,25 @@ jobs:
       - name: 🏄 Copy test env vars
         run: cp .env.example .env
 
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11.1.2
+
       - name: ⎔ Setup node
         uses: actions/setup-node@v4
         with:
           node-version: 22
+          cache: pnpm
 
-      - name: 📥 Download deps
-        uses: bahmutov/npm-install@v1
+      - name: 📥 Install deps
+        run: pnpm install --frozen-lockfile
 
       - name: 📥 Install Playwright Browsers
-        run: npm run test:e2e:install
+        run: pnpm run test:e2e:install
 
       - name: 🛠 Setup Database
-        run: npx prisma migrate deploy && npx prisma generate --sql
+        run: pnpm exec prisma migrate deploy && pnpm exec prisma generate --sql
 
       - name: 🏦 Cache Database
         id: db-cache
@@ -123,17 +147,18 @@ jobs:
           key:
             db-cache-schema_${{ hashFiles('./prisma/schema.prisma')
             }}-migrations_${{ hashFiles('./prisma/migrations/*/migration.sql')
+            }}-seed_${{ hashFiles('./prisma/seed.ts', './prisma.config.ts')
             }}
 
       - name: 🌱 Seed Database
         if: steps.db-cache.outputs.cache-hit != 'true'
-        run: npx prisma migrate reset --force
+        run: pnpm exec prisma migrate reset --force
 
       - name: 🏗 Build
-        run: npm run build
+        run: pnpm run build
 
       - name: 🎭 Playwright tests
-        run: npx playwright test
+        run: pnpm exec playwright test
 
       - name: 📊 Upload report
         uses: actions/upload-artifact@v4

.npmrc

@@ -1,2 +1 @@
-legacy-peer-deps=true
 registry=https://registry.npmjs.org/

.prettierignore

@@ -10,5 +10,10 @@ node_modules
 /tests/fixtures/email/*.json
 /coverage
 /prisma/migrations
+/prisma/sql
+/app/generated/prisma
+.pi
+.pi-lens
 
 package-lock.json
+.cursor

CONTRIBUTING.md

@@ -10,19 +10,26 @@ instructions:
 
 ### System Requirements
 
-- [Node.js](https://nodejs.org/) >= 20.0.0
-- [npm](https://npmjs.com/) >= 8.18.0
+- [Node.js](https://nodejs.org/) ^22.18.0
+- [pnpm](https://pnpm.io/) 11.1.2 (via Corepack recommended)
 - [git](https://git-scm.com/) >= 2.38.0
 
 ### Setup steps
 
 1.  Fork repo
 2.  clone the repo
 3.  Copy `.env.example` into `.env`
-4.  Run `npm install && npm run setup -s` to install dependencies and run
-    validation
+4.  Run `corepack enable && pnpm install && pnpm run setup -s` to install
+    dependencies and set up the local database, Prisma client, and Playwright
+    browsers
 5.  Create a branch for your PR with `git checkout -b pr/your-branch-name`
 
+> Important: `DATABASE_PATH` and `DATABASE_URL` are not interchangeable.
+> `DATABASE_PATH` is the sqlite/LiteFS filesystem path, while Prisma requires
+> `DATABASE_URL` to stay a SQLite URL that starts with `file:`. If you export a
+> global `DATABASE_URL` in your shell, the setup script now prefers the value in
+> the project's `.env` file.
+
 > Tip: Keep your `main` branch pointing at the original repository and make pull
 > requests from branches on your fork. To do this, run:
 >
@@ -50,29 +57,30 @@ cd ./epic-stack
 cp .env.example .env
 
 # Install deps
-npm install
+corepack enable
+pnpm install
 
 # Run the build
-npm run build
+pnpm run build
 
 # setup the database
-npx prisma migrate deploy
+pnpm exec prisma migrate deploy
 
 # generate the prisma client
-npx prisma generate --sql
+pnpm exec prisma generate --sql
 
 # Install playwright browsers
-npm run test:e2e:install
+pnpm run test:e2e:install
 
 # run build, typecheck, linting
-npm run validate
+pnpm run validate
 ```
 
 If that all worked without trouble, you should be able to start development
 with:
 
 ```sh
-npm run dev
+pnpm run dev
 ```
 
 And open up `http://localhost:3000` and rock!

README.md

@@ -12,7 +12,7 @@
 </div>
 
 ```sh
-npx epicli
+pnpm dlx epicli
 ```
 
 [![The Epic Stack](https://github-production-user-asset-6210df.s3.amazonaws.com/1500684/246885449-1b00286c-aa3d-44b2-9ef2-04f694eb3592.png)](https://www.epicweb.dev/epic-stack)

docs/README.md

@@ -32,4 +32,4 @@ in the coming weeks. Stay tuned!
   Most new feature requests people have for the Epic Stack start as examples
   before being integrated into the framework.
 - [Managing Updates](./managing-updates.md) - How to manage updates to the Epic
-  Stack for both the generated stack code as well as npm dependencies.
+  Stack for both the generated stack code as well as pnpm dependencies.

docs/database.md

@@ -59,7 +59,7 @@ you can utilize Fly's `ssh` and `proxy` commands.
 
 - Run in one terminal the command to start Prisma Studio on your desired Fly app
   ```sh
-  fly ssh console -C "npx prisma studio" --app [YOUR_APP_NAME]
+  fly ssh console -C "pnpm exec prisma studio" --app [YOUR_APP_NAME]
   ```
 - Run in a second terminal the command to proxy your local port 5556 to Prisma
   Studio
@@ -68,7 +68,7 @@ you can utilize Fly's `ssh` and `proxy` commands.
   ```
 
 If you have multiple instances of your app running, and you'd like to make edits
-to your database, you will need to run `npx prisma studio` on the primary
+to your database, you will need to run `pnpm exec prisma studio` on the primary
 instance.
 
 - Get a list of your app instances, the `ROLE` column will show which instance
@@ -78,7 +78,7 @@ instance.
   ```
 - Run the console command with the `-s` select flag
   ```sh
-  fly ssh console -C "npx prisma studio" -s --app [YOUR_APP_NAME]
+  fly ssh console -C "pnpm exec prisma studio" -s --app [YOUR_APP_NAME]
   ```
 - Use your arrow keys to select the primary instance
 
@@ -165,11 +165,11 @@ if what you need to seed is a lot of data), so here's an easy way to help out:
    Then modify that file to create the data you want to seed.
 1. Create a temporary database file to seed the data into.
    ```sh
-   DATABASE_URL=file:./seed.local.db npx prisma migrate reset --skip-seed --force
+   DATABASE_URL=file:./seed.local.db pnpm exec prisma migrate reset --skip-seed --force
    ```
 1. Run the custom seed script locally to generate the data you want to seed.
    ```sh
-   DATABASE_URL=file:./seed.local.db npx tsx ./prod-seed.local.ts
+   DATABASE_URL=file:./seed.local.db pnpm exec tsx ./prod-seed.local.ts
    ```
 1. Create a "dump" of the seed database using the `sqlite3` command line tool.
    ```sh nonumber
@@ -186,7 +186,7 @@ If your app has already applied all migrations, then the changes to the
 you can run the following command to apply the migration:
 
 ```sh nonumber
-fly ssh console -C "npx prisma migrate reset --skip-seed --force" --app [YOUR_APP_NAME]
+fly ssh console -C "pnpm exec prisma migrate reset --skip-seed --force" --app [YOUR_APP_NAME]
 ```
 
 > **WARNING**: This will reset your database and apply all migrations. Continue
@@ -305,15 +305,15 @@ You've got a few options:
 
    ```yml
    # exec:
-   #   - cmd: npx prisma migrate deploy
+   #   - cmd: pnpm exec prisma migrate deploy
    #     if-candidate: true
 
-   #   - cmd: npm start
+   #   - cmd: pnpm start
    ```
 
    2. Commit this change and deploy the app to fly.
       - This will make sure that after building the dockerfile and deploying it
-        to the fly machine, `npx prisma migrate deploy` and `npm start` commands
+        to the fly machine, `pnpm exec prisma migrate deploy` and `pnpm start` commands
         won't be executed.
    3. Now that the main machine is up and running, you can SSH into it by
       running `fly ssh console --app [YOUR_APP_NAME]` in the terminal.
@@ -343,10 +343,10 @@ You've got a few options:
 
    ```yml
    exec:
-     - cmd: npx prisma migrate deploy
+     - cmd: pnpm exec prisma migrate deploy
        if-candidate: true
 
-     - cmd: npm start
+     - cmd: pnpm start
    ```
 
    10. Commit this change and deploy the app to fly :tada:

docs/deployment.md

@@ -177,10 +177,10 @@ Create a file at other/docker-entry-point.sh with the contents below.
 ```
 #!/bin/sh -ex
 
-npx prisma migrate deploy
+pnpm exec prisma migrate deploy
 sqlite3 /litefs/data/sqlite.db "PRAGMA journal_mode = WAL;"
 sqlite3 /litefs/data/cache.db "PRAGMA journal_mode = WAL;"
-npm run start
+pnpm run start
 ```
 
 This takes care of applying the prisma migrations, followed by launching the