Skip to content
This repository has been archived by the owner on Jan 4, 2024. It is now read-only.

Latest commit

 

History

History
706 lines (504 loc) · 26 KB

README.md

File metadata and controls

706 lines (504 loc) · 26 KB
Raw

Rewinds

⏪ Rewinds is no longer maintained since Remix v2. Check out the continuation on 🐶 Dogokit / 🐶 Dogokit Remix

Rewinds

Introduction

⏪ Rewinds is a web app starter kit with mainly Remix and Tailwind CSS. Visit the demo at rewinds.mhaidarhanif.com.

This template can still be used as is and quite stable with Remix v1, but will not be updated anymore. See the latest continuation of this starter as 🐶 Dogokit, one of them is being 🐶 Dogokit Remix.

Goals

The goal is to be as productive as possible to ship things fast. So it is a highly opinionated collection of software engineering and web development workflow, interactive UI components, functionality hooks and utilities.

Use this to build any web apps:

  • Personal Website
  • Company Profile
  • Interactive Form
  • Todo List
  • Blog or News
  • Social Media
  • Community Forum
  • Support Desk
  • Art Gallery
  • Job Board
  • Hiring or Recruitment
  • Applicant Tracking System (ATS)
  • Inventory Management
  • Events Management
  • Knowledge Management
  • Admin Panel or Dashboard
  • E-Commerce or Storefront
  • Product or Project Management
  • Content Management System (CMS)
  • Learning Management System (LMS)

Quick start

Starting new? Use this template to generate the repository.

Clone?

git clone [email protected]:mhaidarhanif/rewinds.git

Use npx?

npx create-remix@latest --template mhaidarhanif/rewinds

Deploy quickly?

Deploy with Vercel

Then make sure to explore the repo to rename and replace the contents along the way. As this is a template, not a blank repo generator.

Tech Stack

Primary Tech Stack

The main prerequisites to learn, understand, and use with the stack.

  1. TypeScript: typed language
  2. React: UI library
  3. Remix: web framework
  4. Tailwind CSS: styling
  5. Radix UI: interactive components
  6. Prisma: database ORM
  7. PlanetScale: database management system
  8. Vercel: deployment

If you work as a team, I recommend to:

  1. Use Doppler or Dotenv as secrets management platform to share the environment variables. So you can optionally use .env file. If you need to share quickly EnvShare is good.
  2. Use Vercel Pro to make code review with preview deployments easier.

(Architecture diagram can help later on here)

Complete Tech Stack

The complete stack are Node.js, TypeScript, Remix, Remix Auth, React, Tailwind CSS, Radix UI, Zod, Conform, Prisma ORM, PlanetScale, and Vercel. We also aim to prioritize which has open source option, free-tier, or freemium. Check the GUIDE.md if you need more info on the project setup, structure, and files.

Legends:

  • 🧰 = required or should not be changed
  • 🎉 = 3rd party service or platform
  • 🧩 = optional or interchangeable
  • 💠 = available as open source
  • 🚧 = still in development or not available

Core

Styling and Components

Form Handling and Data Validation

Database and ORM

Auth Provider

Tools: Code Quality

Tools: Deployment

Tools: Domain and DNS and SSL/TLS

Tools: Environment Variable/Secret

Tools: Analytics

  • Vercel Analytics 🧩🎉
    • Enable it on your Vercel projects dashboard
  • Posthog: product platform and data tools 🧩🎉💠
  • Jitsu: data pipeline and ingestion 🚧🧩🎉💠

Tools: Image

Tools: Video

  • Mux: video streaming and management 🚧🧩🎉

Tools: Transactional Email 🚧

Tools: Marketing Email 🚧

Tools: Cache and Rate Limiter

Tools: Payment 🚧

Tools: Testing 🚧

Tools: Container

Extra Tech Stack

Although these are not included, if you need a separate backend/server/service, here are the recommendations:

REST API

GraphQL

tRPC

Auth

Roadmap

Included features for the end users:

  • Premade contents
  • Light and dark mode theme
  • Site layout and routes/pages
  • Admin dashboard and metrics/statistics
  • Register, log in, log out
    • Data validation and check availability
    • Send welcome or verification email
  • Public pages and search
  • User dashboard, profile, settings
    • Manage notes (create, read, update, delete, search)
    • Change profile and avatar image
    • Change email
    • Change and reset password
    • Notification
  • Admin dashboard and search
    • Manage users, notes, etc
  • Various others
    • Share URL with preview image from Open Graph
    • Add to home screen as app on mobile
    • Search data
      • Full text search
    • Upload and manage image assets
    • Map viewer

Included setup for the developers:

  • Full stack type safety with Remix, TypeScript, Zod
    • Follow the practices from the official docs and popular Remix Stacks
    • v2 future flags while still in v1
      • v2 flat routes convention
      • v2 meta data management
      • v2 normalized form method
      • v2 error boundary
      • Tailwind CSS and PostCSS support
      • New dev server with config for HMR/HDR (hot module/data reload)
  • More than 50 of ready to use and 100% customizable UI components
    • Layouts and demo examples
    • Rich text or WYSIWYG editor with TipTap
    • Keyboard shortcuts with cmdk
  • Preselected styles, colors, fonts, icons, and responsive design
    • Customize in Tailwind Config, for brand (primary) and surface (secondary) colors
    • Default avatar image with Dicebear API
    • Icon set system to avoid name conflict
      • Lucide
      • Iconoir
      • Bring your own favorite
  • Database with Prisma ORM and MySQL on PlanetScale
    • tRPC-style or GraphQL-style data models file structure
  • Auth with Remix Auth using a session cookie
  • Data validation with Zod for general and Zodix for Remix loader/action
  • Form handling with Conform
    • Check for unallowed usernames
    • Upload file to Uploadcare
    • Redirect to previous route
    • Password strength meter
  • Image hosting integration
  • Email delivery system
    • Transactional email with Mailjet/Resend and React Email
    • Marketing email with ConvertKit/Bento
  • SEO functions with meta tags
    • robots.txt
    • canonical tag
    • sitemap.xml generator
    • Open Graph and Twitter card
  • Various utilities with external libraries
    • Root loader data for env, theme, user, etc
    • Cache control header
  • No need for CLS loading screens/skeletons, only loading bar on top and loading button state
  • Lighthouse or Pagespeed Insights optimized
  • pnpm, Prettier, ESLint, Stylelint, and many more

Recommended external setup:

Optional workflow setup:

  • Install Kodiak to automate your GitHub pull requests.
  • Install Socket Security to prevent malicious open source dependencies from infiltrating your apps.

More Details

This repo is kind of over-engineered to have high flexibility and cover a lot of use cases for different applications/projects/products, especially what I'm working with several other people.

The components are using shadcn UI as the base components style. And the setup for full stack app development is mostly inspired by T3 Stack. The main difference is this repo example uses Remix by default, not Next.js like those two.

Development

Install Dependencies

Before running your Remix app locally, make sure your project's local dependencies are installed using your preferred package manager agent:

npm install
yarn install
pnpm install

Or if using ni which can autodetect the agent:

pnpm add -g @antfu/ni  # Install once globally
ni                     # Will auto choose npm/yarn/pnpm

Setup Environment Variables/Secrets

These are the main environment variables you need to set up on your own for developing locally:

  • DATABASE_URL
    • Used with Prisma ORM. Get it from local database or PlanetScale
  • UPLOADCARE_PUBLIC_KEY
    • Used with Uploadcare's file uploader widget. Get it from Uploadcare

To manage the environment variables, you can either use:

  1. Plain .env file
  2. Secrets management platform such as Doppler

If using .env fie

cp -i .env.example .env
# -i or --interactive will ask before overwrite

Then edit .env as you need.

If using secrets management platform

Alternatively, it's recommended to use Doppler, or Dotenv, or something similar to manage the credentials. Especially if you're working with a team.

doppler login
doppler setup

To use the secrets directly:

doppler -- pnpm <command>

To download the secrets into the .env file:

doppler secrets download --no-file --format env > .env

⚠️ Make sure to setup the environment variables/secrets here, on Vercel, or on your preferred deployment target. Otherwise the app will break on production. That's why a secrets management platform is recommended to manage them easily. There are also some preset strings in the .env.example which you can copy directly.

Prisma ORM and Database Connection

It's up to you which database/DBMS you want to use with the app that supported by Prisma ORM. This repo is suited to use either your own MySQL instance or MySQL on PlanetScale. But don't use SQLite because it doesn't have @db.Text annotation and model.createMany() function.

Once you have the database URL connection string from PlanetScale MySQL instance, for example:

If using PlanetScale

  1. Create a PlanetScale account which you can sign up for free.
  2. Create a database and get the database URL connection string as DATABASE_URL from there.
  3. Put the DATABASE_URL to the environment variables.
DATABASE_URL='mysql://username:[email protected]/name?sslaccept=strict'

If using local database

Run Docker service and run Docker Compose script:

docker compose up

While in development, you can:

File upload with Uploadcare

This repo using Uploadcare to primarily upload and host the uploaded images and files. If you want the upload component to run, you need to paste your Public API key to UPLOADCARE_PUBLIC_KEY env var.

  1. Create an Uploadcare account.
  2. Go to the Dashboard and get the public key string.
  3. Put it as UPLOADCARE_PUBLIC_KEY to the environment variables.

Run Development Server

Make sure you've generated the latest Prisma schema with nr prisma:generate.

Afterward, start the Remix development server like so based on your preference:

  • Run without HMR: nr dev
  • Run with HMR: nr dev-hmr

Without HMR, it will just run remix dev, the Remix server on development. Then wait until you see this:

Loading environment variables from .env
Remix App Server started at http://localhost:3000

Open up http://localhost:3000 and you should be ready to go!

Alternatively, you can enable/disable HMR by changing this in the remix.config.js. By default we're not using it.

const isUsingHMR = false;

With HMR, it will run both dev:remix and dev:express, the Remix server and the Express server with HMR enabled. Then wait until you see this:

📀 Remix on Express server port :3000
Loading environment variables from .env
💿 Built in 0s

Open up http://localhost:3000 and you should be ready to go!

TypeScript and ESLint Server

When you update some significant changes in the TypeScript config, ESLint config, or just generated a new Prisma schema, you can restart the language server as needed:

> TypeScript: Restart TS Server
> ESLint: Restart ESLint Server
> Prisma: Restart Language Server

Customize some contents

Look up for these comments:

  • EDITME: You can edit them based on your need
  • TODO: You can see that they are in progress

Deployment

Vercel

As this repo was made after having run the create-remix command and selected "Vercel" as a deployment target, you only need to import your Git repository into Vercel, and it will be deployed. Alternatively you can just use the "Deploy to Vercel" button above.

Just keep in mind to set up the environment variables/secret that preferably differentiated for each server environments such as local/development, staging/preview, and production.

Required for the app to run:

# Primary database that connects to Prisma ORM
DATABASE_URL=

# Session secret for cookie after authenticated or logged in
REMIX_SESSION_SECRET=

# Application name
REMIX_APP_NAME=

# Application transactional email
REMIX_APP_EMAIL=

# Upload image assets solution
UPLOADCARE_PUBLIC_KEY=

The session secret for REMIX_SESSION_SECRET can be generated more securely using either Node.js crypto module (JS) or OpenSSL (shell):

$ node scripts/generate-secret.js
1234567890abcdefghijklmnopqrstuvwxyz1234567890

$ sh scripts/generate-secret.sh
yjudrrKv/W4jxzmQqXze9T7DEANxStDtg4YCdfgs/4E=

When managing environment variables/secrets using Doppler, there's the auto sync integration to Vercel:

If you'd like to avoid using a Git repository, you can also deploy the directory by running Vercel CLI:

ni -g vercel
vercel

It is generally recommended to use a Git repository, because future commits will then automatically be deployed by Vercel, through its Git Integration.

To make it automatic for Vercel CI to push the database schema changes (especially to PlanetScale) while building for Preview and Production, you can setup the build command to use the build:ci script instead of regular build.

Put this into the Build Command in the Project Settings:

pnpm build:ci

(Change pnpm to your package manager of choice)

Important Notes

Tailwind CSS Config

Use uicolors.app or tints.dev to generate the color tokens easily. Then replace what's inside tailwind.config.js.

module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: "#f2f9fd",
          // ...
          950: "#0c1c27",
        },
        surface: {
          50: "#f4f8f9",
          // ...
          950: "#040506",
        },
      },
    },
  },
};

Remix Entry Files

This repo already has the entry files. Since Remix v1.14, you might notice that the entry files might be able to be implicitly defined. At the moment, I still suggest revealing or explicitly defining them to make it work smoothly.

npx remix reveal

Remix SEO Configuration

As there's no official way yet to handle SEO related output for metadata and sitemap, here are the options ordered by preference:

  1. balavishnuvj/remix-seo: Collection of SEO utilities like sitemap, robots.txt, etc. for a Remix Application
  2. chaance/remix-seo: A package for easily managing SEO meta and link tags in Remix
  3. fedeya/remix-sitemap: Sitemap generator for Remix applications

Database backup

Syntax to backup using PlanetScale's pscale CLI:

pscale db dump database_name branch --output database_name.dump

For example:

pscale db dump rewinds main --output rewinds.dump

References

General

Remix

React

Tailwind CSS

Inspirations

Also attempt to learn from others like Next.js, NestJS, Passport, tRPC, GraphQL, Swagger (OpenAPI), etc.

Rewinds in the wild

Some other public repos/projects using Rewinds:

Credits

Author

M Haidar Hanif (@mhaidarhanif)

License

The MIT License

Reminder

"Software is a just a tool to help accomplish something for people - many programmers never understood that. Keep your eyes on the delivered value, and don’t over focus on the specifics of the tools" — John Carmack