🐶 Dogokit Beagle

🚧 Migrating to PostgreSQL (Neon) from MySQL (PlanetScale)

🐶Dogokit Beagle is a web app template kit using Remix, React, Tailwind CSS, Radix UI, Prisma ORM, and more. Read the latest updates and details on dogokit/dogokit-beagle.

The goal is to start and be as productive as possible to ship a web app quickly with Remix full stack web framework. It is a highly opinionated collection of application structure, interactive UI components, software engineering and web development workflow, functionality hooks and utilities, also integration with 3rd party services.

Check out:

• Web: https://dogokit-beagle.vercel.app
• Repo: https://github.com/dogokit/dogokit-beagle

Table of Contents

• Quick Start
• Goal
• Prerequisites
• Concept
• Tech Stack
• Setup
• References

Quick Start

Starting new? Use this template to generate the repository.

Clone?

git clone [email protected]:dogokit/dogokit-beagle.git

Use pnpx or pnpm dlx?

pnpx create-remix@latest --template dogokit/dogokit-beagle

Once decided to use this, in order to get the latest README docs possible, replace and remove all explanation in here except the Setup section.

This is a template kit, not a blank repo generator. Customize it based on the actual application needs. Make sure to first explore to understand, rename, and replace the contents along the way.

Goal

The goal is to use this for building 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)
• Software as a Service (SaaS)

Prerequisites

Before using this template, you should already understand and have experience with:

• CLI/Terminal
• HTML
• CSS
• JavaScript
• Node.js
• TypeScript
• React

Concept

Some reasons for making and using this template kit.

• Create a new Remix app or existing one with multiple features quickly
• Setup commonly used development and production parts
  • With pnpm by default
• UI components and styles
  • Light and dark mode theme
  • Styling with Tailwind CSS and Radix UI
  • Bundled with shadcn UI
  • Icon retrieval either with Iconify or manual import
• Database with Prisma ORM
  • Default for PostgreSQL on Neon
  • Option for MySQL on PlanetScale
  • Run local development database instance as a container with Docker and Docker Compose
• Auth (authentication and authorization) built-in
  • With Remix Auth using various strategies: Form and OAuth with 3rd party services
• Various code and utilities
  • Environment variables check with Zod and znv
  • Date and time, encryption, metadata, redirect route, placeholder, sitemap, string functions, timer delay, URL, etc
• Code quality with Prettier, ESLint, Stylelint, Commitlint

Later:

• Sending transactional email with React Email and Resend
• Testing with Vitest and Playwright
• Commands with dogokit CLI or @dogokit/cli

Tech Stack

The main prerequisites to learn, understand, and use with the stack. See the complete and categorized list in the guide to tech stack including things to consider to use later and won't use at all.

(Architecture diagram can help later on here)

• Remix
• React
• TypeScript
• Node.js
• pnpm
• Tailwind CSS
• Radix UI
• Iconify
• Prisma ORM
• MySQL
• Docker and Docker Compose

Setup

Dependencies

Use pnpm to improve productivity and replace npm, so make sure pnpm is installed:

npm i -g pnpm

To run the app locally, make sure the project's local dependencies are installed:

pnpm install

This also run the postinstall script from package.json which by default run prisma generate.

Note: Not using Bun yet as there are still some issues.

Prisma Client Generation

By default installing the modules is also running the postinstall script that generate the Prisma Client (@prisma/client) for it to be used in the app.

If it isn't generated or need to generate manually, run:

pnpm db:gen
# prisma generate

Code Quality

Log, format, lint to check if the setup is fine:

pnpm check
# check: env typecheck prettier eslint stylelint prisma

pnpm fix
# fix: prettier eslint stylelint prisma

Note: Can ignore non-critical warning from ESLint and TypeScript

Environment Variables

Create the .env file from .env.example. This is the one for local development, not production

cp -i .env.example .env

Configure the required environment variables if on local, otherwise in the project settings on other environments.

If necessary, create the .env.production for production access. Adjust accordingly if need for staging, test, etc. Be careful to change the APP_URL on different domains and subdomains.

cp -i .env.example .env.production

Required:

• APP_URL: For example, http://localhost:3000
• SESSION_SECRET: For example, the_secret_text. Anything goes, but better to generate a random string using openssl rand -base64 32 on the terminal or put any long random text.
• DATABASE_URL: For example, mysql://user:password@localhost:3306/dogokit. Continue to read the Database Setup.

Optional:

• NODE_ENV: For example, development
• *_CLIENT_ID and *_CLIENT_SECRET: For OAuth related, check Guide: OAuth

Database Setup

Prisma ORM is used to communicate with the database easily.

For the database, either choose to use MySQL or PostgreSQL (relational database) from local system, Docker container, services like PlanetScale (MySQL) or Neon (PostgreSQL).

If prefer using Docker and Docker Compose for local development, follow this guide on database.

The app is configured primarily to be deployed using PlanetScale. Because of that, the migration files are not needed. Therefore, push the schema directly there. The migration process will be handled through its deploy requests.

This repo template does not recommend MongoDB (document database), although Prisma has a stable support for it. The database provider can still be changed, and the schema and databaase operations might need to adapt.

MySQL Database with PlanetScale

To start quickly, create a PlanetScale account to have a MySQL instance for development and production. After the database has been created, "Get the connection string", select "Prisma", then copy the full DATABASE_URL.

Keep in mind the free plan only allow for 1 database. So either later keep it, delete it when unused, or upgrade the plan. There's also a verification with a payment card, even though it's still free to start.

Also read:

• Prisma with PlanetScale
• PlanetScale with Prisma

Database Operations

Sync between Prisma schema and the database directly, by making schema changes with prisma db push, which can be done regularly while updating the models:

pnpm db:push
# prisma db push

Note: Only need to push the schema in development. No need for migration files.

Even with local development without PlanetScale, pushing the schema directly is still okay when in development or prototyping the schema. After a success push, then it will automatically run prisma generate.

Create users.ts in prisma/credentials folder with the format below. Can focus on certain users who want to be able to access in development, so it doesn't have to be everyone.

export const dataCredentialUsers = [
  {
    fullname: "Example",
    username: "example",
    nickname: "Dogo",
    email: "[email protected]",
    password: "exampleexample",
    roleSymbol: "ADMIN",
  },
]

Then seed the initial data when needed:

pnpm db:seed
# prisma db seed

Build

Check if the build is fine. This als be used to build the app for production.

pnpm build
# remix build

This will also run prisma generate too before the build.

Then try to run the app in production mode:

pnpm start

Then pick a host to deploy it to, such as:

• Vercel
• Netlify
• Fly.io
• Render.com
• Railway.app
• Google Cloud
• Amazon Web Services
• Microsoft Azure

If familiar with deploying node applications, the built-in Remix app server is production-ready. Make sure to deploy the output of remix build

• build/
• public/build/

Development

Finally, develop the app while running the development server:

pnpm dev
# remix dev --manual

Open http://localhost:3000 and it's ready!

What's Next?

Develop the app as usual, the Remix way.

Read the guide to codebase and guide steps to learn more about the setup.

Change the Contents

• Arrange and remove components as needed.
• Find and replace various texts, especially the word Dogokit.

Change Theme Colors

Use kiliman/shadcn-custom-theme to generate shadcn UI CSS variables with Tailwind CSS colors.

For example:

pnpx shadcn-custom-theme primary=indigo secondary=blue accent=violet gray=neutral

Setup some services

• Image upload with Uploadcare
  • UPLOADCARE_PUBLIC_KEY, UPLOADCARE_SECRET_KEY
• Transactional email with Resend
  • RESEND_API_KEY
• Product analytics with Posthog
  • POSTHOG_KEY

Subscribe for the status of the services

• Vercel Status
• PlanetScale Status
• Uploadcare Status
• Resend Status

References

Used By

• 🐾 Allnimal
  • 🐻 Bearmentor
  • 🐱 Catamyst
  • 🐶 Dogokit

Authors

Originally created by @mhaidarhanif in 2023, from the 🐾 Allnimal group (🐻 Bearmentor, 🐱 Catamyst, 🐶 Dogokit)

---

2024 ©️ 🐶 Dogokit