A Remix Demo App

A Remix demo app based on the Remix Indie Stack quick-start project (a simple note-taking application)

Learn more about Remix Stacks.

The original README is further below (with some modifications)

Rationale

The quick-start Indie stack example is a great way to get started with Remix, however, we wanted to create a fuller example with a few goals in mind:

1. We wanted to learn more about Remix.
2. We also wanted to experiment with headless UI systems, in particular Radix and Radix with Tailwind CSS - as a non-CSS-in-JS approach seemed like a better fit for the Remix Philosophy.
3. We also wanted to use Tailwind CSS, combined with 'regular' CSS - configured via postcss to allow the creation of .css sidecar files for any route or component. We've followed the styling guide at Remix for 'surfacing' component-level styles in routes.
4. With the above, we wanted to create a 'skeletal' UI system with core components styled for our basic light and dark themes (with a theme provider courtesy Matt Stobbs and his excellent The Complete Guide to Dark Mode with Remix blog post). Material UI, Bootstrap and others, represent great value and are a good way to kick start a project. The MUI team in particular produce an amazing collection of free-to-use components. But we wanted to try and create a 'back to basics' design system. It's far from perfect, and far from complete - but it was an interesting exercise in hand rolling components, as well as hand picking some of the best available headless components out there and adapting them to suit our needs.

Getting Started

1. Clone or fork this repo.
2. Run npm install to install dependencies. If you don't want package-lock.json to be 'touched', or are planning on submitting a PR - please use npm ci instead.
3. Copy the .env.example file to .env - and optionally fill in your reCAPTCHA keys from Google reCAPTCHA.
4. Run node makeSessionSecret.js to generate your session secret and place it in your .env file above.
5. Copy the prisma/users.example.json file to prisma/users.json - these are the seed user accounts, including an admin user.
6. Run npm run setup to initialize the local SQLite database and seed users.
7. Run npm run dev to start your local development environment.
8. Run rm -rf build and npm run build and npm run start to run a production build.
9. If you'd like to deploy the application to Fly.io - follow the instructions below in the original README. Be sure to rename the application (and unique Fly.io app code) in the name section of package.json and the app section of fly.toml.

Approach

Remix

Remix is pretty cool, and we've tried to do things the Remix way - but, obviously we're new to Remix and so suggestions are welcome. There are a few good example Remix projects out there - including (but not limited to)...

https://github.com/remix-run/react-router-website
https://github.com/jacob-ebey/remix-dashboard-template
https://github.com/jacob-ebey/remix-ecommerce
https://github.com/kentcdodds/kentcdodds.com
https://github.com/epicweb-dev/rocket-rental
https://github.com/mcansh/mcan.sh

Directory Structure

We've seen a few different ways to organize both routes and the overall Remix directory structure. We've mostly followed the original quick-start structure, with the addition of a modules directory (called route-containers, or even components in other projects).

For us modules represent any functional or feature area of the application associated with a route. It's where route-specific React components live - like the Hero.tsx component in the home module for the home / index route.

See the Style System section below for the directory structure of our style system

Data Layer

As in the original quick-start app, this project uses Prisma with User and Note Prisma models for data access. Prisma looks great, and we should probably spent more time with this - but we're new to Prisma as well, having relied on Knex and plain SQL for relational database query building for years now.

We've updated the Prisma /prisma/schema.prisma User model to include an isAdmin field. We've also created a /prisma/users.example.json source user file for seeding users, including an admin account. Follow the Getting Started instructions above to rename this file and seed your database.

Again, as in the original project - we're using SQLite as the database, which makes experimenting with Remix and deploying to Fly.io a breeze.

Style System

The project is configured to use Tailwind CSS and plain CSS via postcss and postcss-cli. There is a 'SMACSS-like' CSS bundle in the root level /shared/css directory - along with the main /shared/css/tailwind.css and /shared/css/app.css source stylesheets. The 'root-level' shared CSS files and imports are processed and placed in the 'app level' styles directory with a corresponding directory structure. We've named the root-level styles directory shared for a reason. ;-)

We've configured postcss-cli with the --base switch, which will re-create the source directory structure in the target output directory. And we've configured the postcss tasks to look for 'side car' stylesheets sitting next to route or module components (see Directory Structure above).

So...

CSS files in the root level /shared directory are processed and placed in the /app/styles/shared app-level styles directory. Any .css files that appear next to components or routes in the routes or modules directories are also processed and placed in the /app/styles/app directory.

The entire system can be illustrated as follows:

Source

/shared
└── css
    ├── app.css
    ├── base
    │   ├── autofill.css
    │   ├── base.css
    │   ├── fonts.css
    │   ├── reset.css
    │   ├── scrollbars.css
    │   └── typography.css
    ├── components
    │   ├── components.css
    │   ├── icon-element.css
    │   └── theme-switcher.css
    ├── layouts
    │   ├── global.css
    │   └── layouts.css
    └── tailwind.css

/app
├── modules
│   ├── home
│   │   ├── hero.css
│   │   ├── hero.tsx
│   │   └── index.ts
└── routes
    ├── index.css
    └── index.tsx

Output

/app
└── styles
   ├── app
   │   ├── modules
   │   │   └── home
   │   │   └── hero.css
   │   └── routes
   │   └── index.css
   └── shared
   └── css
   ├── app.css
   └── tailwind.css

This means of course that you will need to import stylesheets from the /app/styles directory, and not the source route, module or shared CSS directories. In order to 'surface' module-level stylesheets in a route, we followed the styling guide at Remix. It's not a perfect 'co-located' setup - but it works, and it was the best we could come up with for now. Again - suggestions welcome. You can see an example that combines the Hero.css stylesheet with the index.css stylesheet here in the index.tsx route.

Components and Design System

Building a complete design system including design language and tokens is not a small task and we've barely scratched the surface. We've mostly relied on Tailwind CSS utility classes and Tailwind plugins for typography, spacing and color. No effort was made to extract a configurable theme system (apart from the light and dark mode switcher). We simply built what worked. We also think there's value in 'intents' - such as 'primary', 'secondary', 'info', 'success', 'warning', 'danger' - and so button, alert and toast components implement an 'intent' system. We may create mapping definitions for these in tailwind.config.js to make swapping out a base color theme and color system easier.

Below is a brief introduction to the core components, where they came from, and how they've been configured. And here's what's on our current TODO list if you felt like lending a hand (take a look at the Contributions section).

Alert - supports 'intents', and is based on the Radix @radix-ui/react-primitive - which in turn means it supports 'slots' and the asChild prop - allowing you to takeover the alert completely, merging default alert styles and props with your own styles and props ('slot' uses React.cloneElement and mergeProps under the hood. It's very cool). Alerts are animated via Headless UI Transition.

BreadcrumbTrail - is a 'typed' implementation of Breadcrumbs that used Remix's useMatches to match route handle methods - looking for Breadcrumbs. You can see an example here in the app/routes/_app+/notes/notes.$noteId.delete.tsx route. We have no idea if this is the best way to implement a BreadcrumbTrail in Remix - but it seems to work. We think - but may be wrong, that with Remix's file-based router, there's no other way to get or annotate route information, such as a route label - hence this approach. Note too that the handle method can implement as many handle functions as you like by &&-ing or ||-ing additional handle method types (i.e. handle isn't limited to BreadcrumbHandle<T> when Breadcrumbs are implemented on a handle method).

Button - supports 'variants' and 'intents', and is also based on the Radix @radix-ui/react-primitive - which in turn means it supports 'slots' and the asChild prop - allowing you to takeover the button completely, merging default button styles and props with your own styles and props ('slot' uses React.cloneElement and mergeProps under the hood). This makes it trivial to 'wrap' and customize the Remix router Link component as follows:

<Button
  asChild // <-- asChild - render as the children
  variant="outlined"
  intent="primary"
  size="lg"
  className="rounded-lg py-3 px-10 !text-black bg-amber-500/70 hover:bg-amber-400/70">
  <Link to="/notes">
    View notes for {user.email}
  </Link>
</Button>

The core button style system was adapted from Sajad Ahmad Nawabi's excellent Material Tailwind project. The Button component supports Material Ripple Effects - also from Sajad Ahmad Nawabi.

As mentioned in the introduction to this section, we've intentionally removed any advanced theme configuration system for now. We're also aware of Joe Bell's work on CVA - but haven't looked closely enough yet to know whether this would be a better approach.

Card - is a simple div component with default 'card' styling - also implementing Radix asChild.

Container - is one of our building-block layout components supporting content-width layout, and 'shy edges' from max widths.

FocusTrap - is a very cool module for 'trapping' focus within a component - like a modal, dialog, or toast. We're using it in our Toast component. We found this in Jacob Ebey's Remix dashboard app. It was bequeathed to us under the 'Just take it. I do not care.' license.

Input - inputs include Input, Checkbox, and TextArea components. Input and TextArea support labels, help text and error messages. We've not yet implemented a 'variant' system for these components. CheckBox is a functional component wrapper around the Radix Tailwind project Checkbox component.

Pager - a general purpose pager component, supporting both stateful and stateless Remix router modes. Initial styling courtesy of Flowbite Pager.

ScrollToTop - is a simple and dynamic 'scroll to top' component. It will only appear after scrolling down. This is a CSS-styled component with the component stylesheet located at /shared/css/components/scroll-to-top.css.

Section - like Container above, is one of our building-block layout components.

Select - is a functional component wrapper around the Radix Tailwind project Select component.

Table - components include all styled table elements and a TablePager component. The TablePager component is dependent on the excellent TanStack Table component (formerly React Table), however, this probably isn't the 'Remix way'. A better implementation might be to surround all of the pager controls in a form element with a 'get' method and action that simply submits updated url search params (aka query string parameters). Initial TablePager styling courtesy of Flowbite Pager.

ThemeSwitch - is our component for changing between light and dark themes via ThemeProvider. Our initial theme strategy was based on Matt Stobbs' excellent blog post - The Complete Guide to Dark Mode with Remix. We've since refactored things a bit and are now only detecting prefers-color-scheme via User Preference Media Features Client Hints Headers. You can read more about our thinking and the choices we made here in this Github issue - Refactor ThemeProvider and prefers-color-scheme detection

Toast - is an 'intent'-enabled functional component wrapper around the Radix Tailwind project Toast component.

Tooltip - is a functional component wrapper around the Radix Tailwind project Tooltip component.

Routing

Routing is courtesy Remix Flat Routes. It took a little reading (and some help from @kiliman) to 'grok' the way in which you define routes, but it produces a very nice file structure - which in turn makes for quick filename searches for routes files. For example...

.
├── _actions+
│   └── actions.set-theme.tsx
├── _app+
│   ├── _app.tsx
│   ├── account.$userId.email.tsx
│   ├── account.$userId.password.tsx
│   ├── account.index.tsx
│   ├── notes.$noteId.tsx
│   ├── notes.$noteId_.delete.tsx
│   ├── notes.$noteId_.edit.tsx
│   ├── notes.index.tsx
│   └── notes.new.tsx
├── _auth+
│   ├── _auth.tsx
│   ├── sign-in.tsx
│   ├── sign-out.tsx
│   └── sign-up.tsx
├── _landing+
│   ├── _landing.tsx
│   ├── index.css
│   └── index.tsx
├── admin+
│   ├── _admin.tsx
│   ├── index.tsx
│   ├── users.tsx
│   └── users_.$userId.tsx
├── healthcheck.tsx
├── theme-radix-dialog.tsx
├── theme-radix-toast.tsx
├── theme-tailwind-forms.tsx
└── theme.tsx

Which produces the following React Router routes...

<Routes>
  <Route file="root.tsx">
    <Route path="actions/set-theme" file="routes/_actions+/actions.set-theme.tsx" />
    <Route file="routes/_app+/_app.tsx">
      <Route path="account/:userId/email" file="routes/_app+/account.$userId.email.tsx" />
      <Route path="account/:userId/password" file="routes/_app+/account.$userId.password.tsx" />
      <Route path="notes/:noteId" file="routes/_app+/notes.$noteId.tsx" />
      <Route path="notes/:noteId/delete" file="routes/_app+/notes.$noteId_.delete.tsx" />
      <Route path="notes/:noteId/edit" file="routes/_app+/notes.$noteId_.edit.tsx" />
      <Route path="notes/new" file="routes/_app+/notes.new.tsx" />
      <Route path="account/" index file="routes/_app+/account.index.tsx" />
      <Route path="notes/" index file="routes/_app+/notes.index.tsx" />
    </Route>
    <Route file="routes/_auth+/_auth.tsx">
      <Route path="sign-in" file="routes/_auth+/sign-in.tsx" />
      <Route path="sign-out" file="routes/_auth+/sign-out.tsx" />
      <Route path="sign-up" file="routes/_auth+/sign-up.tsx" />
    </Route>
    <Route file="routes/_landing+/_landing.tsx">
      <Route index file="routes/_landing+/index.tsx" />
    </Route>
    <Route path="admin" file="routes/admin+/_admin.tsx">
      <Route index file="routes/admin+/index.tsx" />
      <Route path="users" file="routes/admin+/users.tsx" />
      <Route path="users/:userId" file="routes/admin+/users_.$userId.tsx" />
    </Route>
    <Route path="healthcheck" file="routes/healthcheck.tsx" />
    <Route path="theme-radix-dialog" file="routes/theme-radix-dialog.tsx" />
    <Route path="theme-radix-toast" file="routes/theme-radix-toast.tsx" />
    <Route path="theme-tailwind-forms" file="routes/theme-tailwind-forms.tsx" />
    <Route path="theme" file="routes/theme.tsx" />
  </Route>
</Routes>

Validation and Errors

Data input is validated by both client- and server-side Zod schemas and React Hook Form Zod resolvers - with errors reported either at field-level for form data errors, or via general alerts for any non-field-based errors. We've tried to implement utility methods for server and client errors returned via Zod, as well as other conditions such as unique constraint violations. You can see an example in the /app/routes/_app+/account.$userId.email.tsx route.

i18n and L10n

We've yet to implement localization / translations, although another interesting aspect of Remix as a 'first class' SSR framework, is that client preferred language detection can be done via the Accept-Language HTTP header.

Sergio Xalambrí appears to show the way....

https://sergiodxa.com/articles/localizing-remix-apps-with-i18next
https://github.com/sergiodxa/remix-i18next

This is high on our TODO list

A11y

We're committed to enabling people with limited abilities to use websites. Many of the components we've used have been built with a11y in mind. We've also tried to include WAI-ARIA compliant roles and labels where appropriate although there is almost certainly more to do here. We've not yet completed a WAI-ARIA review of this project, and so yet again, suggestions, or raised issues related to omissions or errors greatly appreciated.

ESLint

We've included the eslint-config-airbnb-typescript plugin in our ESLint configuration, along with a handful of custom rules. The rest comes from the quick-start app.

Tests

We removed Cypress and have configured Playwright for end-to-end tests. Vitest is still enabled - which explains the test, tests, tests-examples directories. We'll follow Kent Dodd's lead here and er... em... we're going to write some tests.
¯\(ツ)/¯

Also high on our TODO list

Docker

The Docker image that came with the quick-start app for deployment to Fly.io (and Firecracker microVMs) has been updated to Node v18 LTS. There are also docker-build.sh, docker-compose.yml and docker-exec.sh files that will allow you to build and run the Docker image and container locally if you'd like to test a local Docker environment. Note that we don't currently mount the SQLite data directory, and so starting a new container instance will create a new database. This is also a great start for creating your own deployment pipeline via Docker and say for example AWS ECS, or other.

The Stack

Assuming this effort doesn't suck, and after a little more work it turns out there's value here for anyone here getting started with Remix and a headless UI strategy, we'll convert this project to a Remix stack. Stay tuned!

Contributions

Feedback, thoughts and suggestions are most welcome. Issues and even PRs would be super too! We've created TODO list.

We use a husky task and Conventional Commits for our commit messages.

@commitlint/cli @commitlint/config-conventional are included in the dev dependencies of this project.

Common commit message types according to commitlint-config-conventional (based on the Angular convention) can be:

• build
• chore
• ci
• docs
• feat
• fix
• perf
• refactor
• revert
• style
• test

To prepare husky and the conventional commit task for development run the following:

npm run prepare - will prepare local husky tasks.

Note that the .husky/commit-msg task should already be present when you clone this repo. If it's not, you can add it with the following:

npx husky add .husky/commit-msg 'npx commitlint --edit $1' - will add the commit message task.

Hope some of this is of help to those of you just getting started with Remix and headless UI component systems (as we are).

 

---

Original Indie Stack quick-start README - What's in the stack

• 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 Prisma
• Styling with Tailwind
• Local third party request mocking with MSW
• Unit testing with Vitest and Testing Library
• Code formatting with Prettier
• Linting with ESLint
• 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.

Quickstart

Click this button to create a Gitpod workspace with the project set up and Fly pre-installed

Development

• This step only applies if you've opted out of having the CLI install dependencies for you:

  npx remix init

• Initial setup: If you just generated this project, this step has been done for you.

  npm run setup

• Start dev server:

  npm 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: rachel@remix.run
• 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 Prisma 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/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 remix-infonomic-io-c6b7
  fly apps create remix-infonomic-io-c6b7-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 remix-infonomic-io-c6b7
  fly secrets set SESSION_SECRET=$(openssl rand -hex 32) --app remix-infonomic-io-c6b7-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 remix-infonomic-io-c6b7
  fly volumes create data --size 1 --app remix-infonomic-io-c6b7-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

cy.login()
// you are now logged in as a new user

We also have a utility to auto-delete the user at the end of your test. Just make sure to add this in each test file:

afterEach(() => {
  cy.cleanupUser()
})

That way, we can keep your local db clean and keep your tests isolated from one another.

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 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 (like the VSCode Prettier 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.