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)
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:
.css
sidecar files for any route or component. We've followed the styling guide at Remix for 'surfacing' component-level styles in routes.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..env.example
file to .env
- and optionally fill in your reCAPTCHA keys from Google reCAPTCHA.node makeSessionSecret.js
to generate your session secret and place it in your .env
file above.prisma/users.example.json
file to prisma/users.json
- these are the seed user accounts, including an admin user.npm run setup
to initialize the local SQLite database and seed users.npm run dev
to start your local development environment.rm -rf build
and npm run build
and npm run start
to run a production build.name
section of package.json
and the app
section of fly.toml
.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
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
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.
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.
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 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>
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.
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
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.
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.
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
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.
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!
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:
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).
Not a fan of bits of the stack? Fork it, change it, and use npx create-remix --template your/repo
! Make it your own.
Click this button to create a Gitpod workspace with the project set up and Fly pre-installed
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:
rachel@remix.run
racheliscool
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.
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:
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 yourfly.toml
file. Otherwise, you will not be able to deploy.
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.
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
.
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.
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.
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.
For lower level tests of utilities and individual components, we use vitest
. We have DOM-specific assertion helpers via @testing-library/jest-dom
.
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
.
This project uses ESLint for linting. That is configured in .eslintrc.js
.
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.