gitsell: A Remix-Vite web app on Cloudflare Pages

💚 Credo

Core principles of this repo:

Run on any range of devices and at any network speed
Be free to host and easily migratable in case a provider shuts down
Be easy on the environment by not running when not in use and using the most efficient resources available when running
Be secure

Some key ways we've achieved the above:

Use SQLite over PostgreSQL for its ability to quickly scale to 0 and back up, and use Turso specifically for its guarantee to continue offering a free tier due to its minimal cost
Use serverless Cloudflare, which has publicly reaffirmed its commitment to its free tier and its ability to offer it given its efficiency, instead of serverful containers that always run (costing money and energy)
Use minimal 3rd-party dependencies to minimize vulnerability surface area and bundle size transmitted over the network
Use HTML and CSS over JS for its network and CPU efficiency as well as its improved responsiveness and accessibility
Use purely additive WebSocket functionality via PartyKit which is owned by Cloudflare and has a generous free tier since using durable objects (required for event-driven SSE or WS) directly requires being on the paid tier. App core experience continues working perfectly even without WebSocket.

📖 Resources

App
Hosting
- Cloudflare Pages
  - Cache Rules are configured via dashboard
  - Change TLS from "flexible" to "full (strict)"—may be needed for caching
  - Cloudflare requires a custom domain for caching to work so set DNS up (Namecheap guide)
  - Service bindings
Database
- Turso
- Drizzle ORM
Design
- Tailwind CSS
  - V4 changelog
- Tailwind References
WebSocket (optional)
- PartyKit
Email (optional)
- DNS verification
- Email routing
Cloudflare Turnstile (optional)

🧑‍💻 Development setup

Install turso CLI and log in
Create a new GitHub OAuth App
- Application name: Something (Development)
- Homepage URL: http://localhost:5173
- Authorization callback URL: http://localhost:5173/login/github
Set GITHUB_CLIENT_ID in wrangler.toml
Generate a new client secret in the GitHub App settings and set GITHUB_CLIENT_SECRET in .dev.vars
Create a new GitHub App
- GitHub App name: Something (Development)
- Homepage URL: http://localhost:5173
- Callback URL: http://localhost:5173/sell/sync/github
- Webhook URL: [ngrok domain]/webhook/github
- Permissions:
  - Administration: read and write
  - Contents: read only
  - Webhooks: read and write
Set:
- GITHUB_APP_ID in wrangler.toml
- GITHUB_APP_CLIENT_ID in wrangler.toml
- GITHUB_APP_URL in wrangler.toml
- GITHUB_APP_CLIENT_SECRET in .dev.vars
- GITHUB_APP_PRIVATE_KEY in .dev.vars
- GITHUB_APP_SECRET_TOKEN in .dev.vars
Create a Stripe account following the prerequisites here
Set:
- STRIPE_SECRET_KEY in .dev.vars
- STRIPE_WEBHOOK_SIGNING_SECRET in .dev.vars
Install bun
bun i to install dependencies
In Terminal tab 1, turso dev to run the database in memory. No environment variables are needed since the database is running locally on its default port
In another Terminal tab, bun run build:db to apply migrations to the running database
In Terminal tab 2, bun --cwd apps/git-sell ngrok http 5173 --domain=[your static domain]
- You will be prompted to log in to ngrok
- It's recommended to claim a static domain
In Terminal tab 3, bun run dev
In Terminal tab 4, bunx partykit dev if you want to use purely additive websocket functionality

🤖 CI/CD

If using WebSocket, https://docs.partykit.io/guides/setting-up-ci-cd-with-github-actions/
For app, create Cloudflare API token like https://developers.cloudflare.com/workers/wrangler/ci-cd/#api-token but add "Cloudflare Pages — Edit" permission
Disable automatic deployments in Cloudflare Pages settings