README.md

Remix with WorkOS

Remix auth + Multi-Factor Authentication (MFA) example app. Powered by the WorkOS Multi-factor authentication API

Built using the following tools and libraries:

• Remix - fullstack React framework built on top of Web standards
• WorkOS MFA API + WorkOS SDK - WorkOS API that enables you to add SMS/TOTP (Time-based One Time Passwords) verification codes
• TailwindCSS - utility first CSS framework
• Prisma - type-safe ORM
• Radix UI - unstyled, accessible, React components
  • Alert Dialog
  • Icons
  • Dialog
  • Radio group
• react-hot-toast - library for displaying toasts
• react-verification input - masked input for submitting verification codes
• TypeScript - type-safe JS

Set up the project locally

1. Clone the repository and install the dependencies by running the following commands:

git clone https://github.com/workos/remix-mfa

cd remix-mfa

npm install

2. Rename the .env.example file to .env by running the following command:

cp .env.example .env

1. First, create a WorkOS account. Next, in the left sidebar, navigate to the "API keys" tab, create a new API key and add it to the .env file in your project .

WORKOS_API_KEY=''

Note: You can test WorkOS for free, you only get charged when you go to production

4. Set the SESSION_SECRET environment variable. You can generate a random secret by running the following command:

openssl rand -base64 32

5. Setup Prisma by running the following command:

npx prisma db push

They will create a prisma/data.db SQLite file

6. Start the development server

npm run dev

You'll see the app running at http://localhost:3000. Navigate to the sign up page at http://localhost:3000/signup and create a new user. You'll then be logged in and you can go to the settings page where you can configure MFA.

Code Architecture

You'll see the following folder structure:

remix-with-workos/
┣ app/
┃ ┣ components/
┃ ┃ ┣ auth/
┃ ┃ ┣ layout/
┃ ┃ ┣ settings/
┃ ┃ ┗ shared/
┃ ┣ hooks/
┃ ┃ ┣ useMatchesData.ts
┃ ┃ ┣ useOptionalUser.ts
┃ ┃ ┗ useUser.ts
┃ ┣ lib/
┃ ┃ ┣ prisma.server.ts
┃ ┃ ┗ workos.server.ts
┃ ┣ models/
┃ ┃ ┗ user.server.ts
┃ ┣ routes/
┃ ┃ ┣ index.tsx
┃ ┃ ┣ login.tsx
┃ ┃ ┣ logout.tsx
┃ ┃ ┣ settings.tsx
┃ ┃ ┣ settings.two-factor-authentication.tsx
┃ ┃ ┗ signup.tsx
┃ ┣ styles/
┃ ┃ ┗ app.css
┃ ┣ utils/
┃ ┃ ┣ validation/
┃ ┃ ┣ displayToast.server.ts
┃ ┃ ┣ redirectSafely.server.ts
┃ ┃ ┗ session.server.ts
┃ ┣ entry.client.tsx
┃ ┣ entry.server.tsx
┃ ┗ root.tsx
┣ prisma/
┃ ┣ data.db
┃ ┗ schema.prisma
┣ public/
┃ ┗ favicon.ico
┣ styles/
┃ ┗ app.css
┣ .env.example
┣ .eslintrc
┣ .gitignore
┣ .prettierrc
┣ README.md
┣ package-lock.json
┣ package.json
┣ postcss.config.js
┣ remix.config.js
┣ remix.env.d.ts
┣ server.js
┣ tailwind.config.js
┣ tsconfig.json
┗ vercel.json

• /app directory:
  • /app/components:
    • components/auth: directory containing auth-related components (login form, verification input, two-factor form)
    • /components/layout: layout components (Navbar, Footer, etc.)
    • /components/settings: components for the settings page (configuring MFA, deleting a user's account, changing password)
    • components/shared: reusable, shared components (e.g button, form input, etc.)
    • components/hooks: reusable React hooks used on the client
  • app/lib: contains files where different libraries are instantiated
  • app/models: contains database CRUD logic/operations
  • app/routes: contains the different routes for the app.
  • app/styles: generated tailwindcss utilities coming from /styles
  • app/utils: utility functions
  • entry.client.tsx:
  • entry.server.tsx:
  • root.tsx
• /prisma:
  • data.db: SQLite database
  • schema.prisma: database schema (download the Prisma VS code extension for syntax highlighting)
• tailwind.config.js and postcss.config.js: tailwind configuration files

There's also linting using ESLint and code formatting using Prettier

This app is configured to deploy to Vercel, but you can deploy to other platforms as well. Check out the Remix deployment docs to learn more

Going to production

This demo uses SQLite for simplicity purposes, however for you app you might go with a different database solution such as PostgreSQL, MySQL or MongoDB. To switch database providers, all you need to do is provider field in your /prisma/schema.prisma file.

Future improvements

List of features

• Create an email sending endpoint
  • Send an email to the the logged in user when an authentication factor has been added
  • Send an email to the logged in user when an authentication factor has been removed
• Forgot password functionality