House Stack

pnpm create remix@latest --template drewjs/house-stack

Note: pnpm is the default package manager for this project. Other package managers may require minor changes before deployment.

Learn more about Remix Stacks.

What's Included

• Fly app deployment with Docker
• Production-ready SQLite Database
• Healthcheck endpoint for Fly backups region fallbacks
• GitHub Actions for deploy on merge to production and staging environments
• Email/Password Authentication with cookie-based sessions
• Database ORM with Drizzle
• Styling with Tailwind
• End-to-end testing with Playwright
• Local third party request mocking with MSW
• Unit testing with Vitest and Testing Library
• Linting and formatting with Biome
• Static Types with TypeScript

Not a fan of bits of the stack? Fork it, change it, and use npx create-remix --template your/repo! Make it your own.

Development

• First run this stack's remix.init script and commit the changes it makes to your project.

  npx remix init
  git init # if you haven't already
  git add .
  git commit -m "Initialize project"

• Initial setup:

  pnpm run setup

• Start dev server:

  pnpm run dev

This starts your app in development mode, rebuilding assets on file changes.

The database seed script creates a new user with some data you can use to get started:

• Email: [email protected]
• Password: racheliscool

Relevant code:

This is a pretty simple note-taking app, but it's a good example of how you can build a full stack app with Drizzle and Remix. The main functionality is creating users, logging in and out, and creating and deleting notes.

• creating users, and logging in and out ./app/models/user.server.ts
• user sessions, and verifying them ./app/utils/session.server.ts
• creating, and deleting notes ./app/models/note.server.ts

Deployment

This Remix Stack comes with two GitHub Actions that handle automatically deploying your app to production and staging environments.

Prior to your first deployment, you'll need to do a few things:

• Install Fly

• Sign up and log in to Fly

  fly auth signup

  Note: If you have more than one Fly account, ensure that you are signed into the same account in the Fly CLI as you are in the browser. In your terminal, run fly auth whoami and ensure the email matches the Fly account signed into the browser.

• Create two apps on Fly, one for staging and one for production:

  fly apps create house-stack-template
  fly apps create house-stack-template-staging

  Note: Make sure this name matches the app set in your fly.toml file. Otherwise, you will not be able to deploy.

  • Initialize Git.

  git init

• Create a new GitHub Repository, and then add it as the remote for your project. Do not push your app yet!

  git remote add origin <ORIGIN_URL>

• Add a FLY_API_TOKEN to your GitHub repo. To do this, go to your user settings on Fly and create a new token, then add it to your repo secrets with the name FLY_API_TOKEN.

• Add a SESSION_SECRET to your fly app secrets, to do this you can run the following commands:

  fly secrets set SESSION_SECRET=$(openssl rand -hex 32) --app house-stack-template
  fly secrets set SESSION_SECRET=$(openssl rand -hex 32) --app house-stack-template-staging

  If you don't have openssl installed, you can also use 1Password to generate a random secret, just replace $(openssl rand -hex 32) with the generated secret.

• Create a persistent volume for the sqlite database for both your staging and production environments. Run the following:

  fly volumes create data --size 1 --app house-stack-template
  fly volumes create data --size 1 --app house-stack-template-staging

Now that everything is set up you can commit and push your changes to your repo. Every commit to your main branch will trigger a deployment to your production environment, and every commit to your dev branch will trigger a deployment to your staging environment.

Connecting to your database

The sqlite database lives at /data/sqlite.db in your deployed application. You can connect to the live database by running fly ssh console -C database-cli.

Getting Help with Deployment

If you run into any issues deploying to Fly, make sure you've followed all of the steps above and if you have, then post as many details about your deployment (including your app name) to the Fly support community. They're normally pretty responsive over there and hopefully can help resolve any of your deployment issues and questions.

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 our End-to-End tests in this project. You'll find those in the test directory. As you make changes, add to an existing file or create a new file in the test/e2e directory to test your changes.

To run these tests in development, run pnpm run test:e2e:dev which will start the dev server for the app as well as the Playwright client.

Vitest

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

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 pnpm run typecheck.

Linting

This project uses Biome for linting and formatting. That is configured in ./biome.json. It's recommended to set up Biome for your editor as well. See docs here

If you would like to enable import sorting set organizeImports.enabled = true. You will need to run pnpm biome check --apply . or configure your editor to automatically run on save

Class sorting for CSS utilities like Tailwind is also available, however it is still under development. details here

Special Thanks

• Remix team - for this cool framework that makes making websites super fun
• Epic Stack - for many of the ideas and other inspiration in the project