stripe-stack: A TypeScript repository from nzambello

Live Demo · Deployment Documentation · Twitter

A Stripe focused Remix Stack that integrates User Subscriptions, Authentication and Testing. Driven by Prisma ORM. Deploys to Fly.io

Features

Stripe Stack has been built on top of Barebones Stack, including all its base features.

Base Features

Fly app Deployment with Docker.
Database ORM with Prisma.
Production Ready with SQLite and PostgreSQL.
GitHub Actions for Deploy on merge to Production and Staging environments.
Styling with Tailwind.css + Tailwind Prettier-Plugin.
Healthcheck Endpoint for Fly backups Region Fallbacks.
End-to-End testing with Playwright.
Unit Testing with Vitest and Testing Library.
Local third party request mocking with MSW.
Linting with ESLint.
Code formatting with Prettier.
Static Types with TypeScript.

Implemented Features

Authentication Ready with Remix-Auth that includes: Socials Strategies and Form Strategy.
Stripe Subscriptions with support for Multiple Plans, Upgrade / Downgrade and Customer Portal.
Support for Javascript developers with continuous updates over time based on remix.init.

Learn more about Remix Stacks.

Quickstart

Stripe Stack has support for multiple database based on Prisma. The installer will prompt a selector allowing you to choose the database your project will run on. Deployment files will be updated matching the required criteria to successfully deploy to Fly.io

To get started, run the following commands in your console:

# Initialize template in your workspace:
npx create-remix@latest --template dev-xo/stripe-stack

# You will be prompted to select the database your project will run on.
# ...

# Start dev server:
npm run dev

Notes: Important❗️: Cloning the repository instead of initializing it with the above commands, will result in a inappropriate experience. This template uses remix.init to configure itself and prepare your environment.

Getting Started

The following section will be splitted into three quick threads: Live Demo, Development and Production.

Live Demo

Template's Demo has been built to be really simple to test, being able to show all its provided features. Here is the workflow we can follow to test it:

Log in with your preferred authentication method.
Select a Subscription Plan.
Fill Stripe Checkout inputs with default development values. (Check Notes)

Done! We should be redirected back to the app with selected Stripe Plan already set.

Notes: Stripe test mode uses the following number: 4242 as valid values for Card Information. Type it as much times as you can on each available input to successfully complete Checkout step.

Development

Understanding our development workspace will keep us productive.

Usage

Template can be used in the way you like. Feel free to remove all the HTML code you don't need, keeping just the loaders and actions from Remix.

Code that is necessary for the template to work as expected, has been marked as @required.

Prisma Migrations

If your database choice was PostgreSQL, you will need to run Prisma migrations with your Postgres client running on the background. In order to accomplish this, feel free to remove the folder inside /prisma called /migrations, and run npx prisma migrate dev --name init to properly setup them.

Folder Structure

Let's review some of template's important folders:

├── models          # Stores database interactions.
├── services        # Stores sessions, configs, utils and template initializers.
  ├──                 This folder could also be called "lib" or "modules".

├── routes
  ├── api           # Stores Stripe Webhook Endpoint, and any realted API call.
  ├── resources     # Stores app logic, redirects and session updates.

Authentication

Stripe Stack provides Social and Form Authentication.

Social Authentication

To start using Social Authentication, we'll need to get the secret API Keys from the following Providers. Below here you can find all template's Providers OAuth Documentations.

Usually Social Providers will ask you for a Callback URI / Redirect URL. An example of a Callback URI for this template will look like the following one: https://my-deployed-app.fly/auth/provider/callback.

Replace /provider with the one you are trying to setup. Available providers are: google, twitter, github and discord. Remember to set your Provider API Keys into template's .env file.

Email / Password Authentication

Using this method is pretty straightforward. The only thing we have to know is that in order to allow the user recover its password, we'll need to use an Email Service.

This template uses Sendinblue, an Email Service that does not require Credit Card for registration, either use. It's limited to 300 Emails per day, but it's good enough for development propouses.

Let's see how we can set up this service:

Create an account at Sendinblue.
Go to Menu, and click on SMTP & API.
Create and Copy the provided API Key.

Done! Paste it into template's .env file as EMAIL_PROVIDER_API_KEY.

Stripe Webhook - Development

In order to start receiving Stripe Events to our Webhook Endpoint, we'll have to install Stripe CLI. Once installed, keep the following command running on the background:

stripe listen --forward-to localhost:3000/api/webhook

The above command will provide us with a Webhook Signing Secret that has to be set in template's .env as DEV_STRIPE_WEBHOOK_ENDPOINT_SECRET.

Stripe Products

From Stripe Products Dashboard, create as many products as you want. Remember to update their secret API Keys in template's .env as well as the product descriptions from /services/stripe/stripe-plans.

Production

Stripe Webhook - Production

In order to start receiving Stripe Events to our deployed app, we'll need to setup our Production Webhook:

Visit Stripe Dashboard Webhooks
Create a new Webhook Endpoint.
Set your deployed app Webhook Endpoint URL into Endpoint URL input. (Check Notes)
Reveal the Signing Secret value that has been provided from Stripe Webhook page and set it as PROD_STRIPE_WEBHOOK_ENDPOINT_SECRET in template's .env file.

Notes: This is an example of a Deployed Webhook Endpoint URL: https://my-deployed-app.fly.dev/api/webhook

Deployment

Stripe Stack has support for SQLite and PostgreSQL. In order to keep a better track and an easier maintenance of each deployment documentation, we moved each one to its own file.

Check SQLite DEPLOYMENT.md or PostgreSQL DEPLOYMENT.md to get your app to production.

GitHub Actions

We use GitHub Actions for continuous integration and deployment. Anything that gets into the main branch will be deployed to production after running tests, build, etc. Anything in the dev branch will be deployed to staging.

Testing

Playwright

We use Playwright for End-to-End tests. You'll find those in the tests/e2e directory. As you make changes, add to an existing file or create a new file in the tests/e2e directory to test your changes.

To run these tests in development, run npm run test:e2e:dev.

Vitest

For lower level tests of utilities and individual components, we use vitest. We have DOM-specific assertion helpers via @testing-library/jest-dom.

To run these tests in development, run npm run test or npm run test:cov to get a detailed summary of your tests.

Type Checking

This project uses TypeScript. It's recommended to get TypeScript set up for your editor to get a really great in-editor experience with type checking and auto-complete. To run type checking across the whole project, run npm run typecheck.

Linting

This project uses ESLint for linting. That is configured in .eslintrc.js.

Formatting

We use Prettier for auto-formatting in this project. It's recommended to install an editor plugin to get auto-formatting on save. There's also a npm run format script you can run to format all files in the project.

This template has pre-configured prettier settings on .package-json. Feel free to update each value with your preferred work style.

Contributing

Contributions are Welcome! Jump in and help us improve this Community Template over time!

Contributing Guide Docs.
Public Project Roadmap Check template's TODOs, fixes and updates.

Support

If you find this template useful, support it with a Star ⭐
It helps the repository grow and gives us motivation to keep working on it. Thanks you!

Acknowledgments

A shout out to @vueeez who just jumped on Twitter DMs, contributing on Twitter Authentication Strategy.

nzambello/stripe-stack