nextjs-boilerplate

A full stack example of technologies for a production ready foundation. 🔥 Next.js + NextGQL Graphql + Drizzle ORM + NextUI (Tailwind)

Demo: https://nextjs-boilerplate-adam-lane.vercel.app/

Getting Started

• Install node lts+. Node necessary to build/run next.js
• Install Docker engine. Rancher Desktop (recommended)
• Install package manager. bun (recommended)
  • npm install -g bun
  • configure these bun binary lockfile diff git config settings
• Copy .env.example to .env.local and edit variables (app should come up with default values but you will need real values for auth to work)
• bun dev

Development

• bun dev - package check, docker (db), db migrations, graphql codegen watcher, next dev

Templating

Rapidly develop new code without manual copy/paste or maintaining separate template files. Copy source patterns to a new entity structure using comments embedded in files.

• bunx clone-code ENTITY_HOOK <NewEntity> ./src

See top of task.model.ts for example and CloneCode for details.

Testing

• bun run test - vitest unit tests, playwright e2e tests

Features

Frontend

• ⚡ Next.js Fullstack react framework with SWC
• NextUI react component library
  • NextUI-Admin admin layout and table components out of the box -💎 Tailwind CSS composable utility classes
  • Tailwind Variants - Create reusable css (css-in-js alternative)
• 💖NextGQL Client GraphQL with secure sensible defaults out of box
  • Urql graphql (state management, subscriptions, etc)
  • Graphql code generation with client preset
  • File Upload and subscriptions example
• next-secure secure headers for maximum security
• env-valibot environment variable validation using valibot
• 🔒 firebase auth edge compatible
• react-hook-form for simple and high performance forms
• 🤖 SEO, JSON-LD and Open Graph tags with Next metadata
• 🎉 Storybook for component driven UI development
• serwist service worker with optimized configuration
• next-intl localization with app directory and middleware
• ✅ TypeScript strict with ts-reset library for extra type safety
• 📏 ESLint and Prettier on commit with Husky
• ⚙️ Bundler Analyzer after new dependencies to make sure client size is as expected

Backend

• ⚡ Next.js API routes. Fullstack and serverless friendly
• 💖NextGQL Server GraphQL with secure sensible defaults out of box
  • Yoga serverless/edge compatible graphql server
  • Pothos "code first" typesafe graphql models
  • Graphql Armor security defaults
• Database
  • docker-compose start db without local install
    • CockroachDB free tier, scalable, production ready.
  • drizzle-helpers optimized connection, migration, and ORM functions
    • drizzle db migrations and typesafe sql query builder
    • postgres.js fast postgres driver over traditional pg

Dev Ops

• error logging - sentry (see src/pages/_app.js)
• 🛠️ ️fixpack package.json normalization
• 🚓 commit messages validated with Commitlint
• Playwright e2e tests
• ViTest unit tests
• GitHub Actions tests

TODO (potentially)

• catch FirebaseError: Firebase: Error (auth/popup-closed-by-user).
• switch hasty todo list to github tracking
• strict-dynamic CSP in middleware vs next.config.js headers
  • remove static from auth pages so it gets dynamic csp headers
• better env file handling between a team than .env.local. There must be something better.
• error handling review
• email templating with mjml
• typesafe routes vs strings
  • kinda started in routes.js but needs more work
  • may already be handled by next-intl
• graphql enhancements
  • endpoint post uses csrf
  • persisted queries (blocked by issue with codegen)
• analytics
• Sitemap.xml and robots.txt with next-sitemap
• Cloudflare next-on-pages verification. Had sentry bugs that issue says is fixed now.
• figure out a good way for demo to get into /admin side of things
• setup dependency checking on github actions with Renovate
• playwright tests
  • running with github actions
  • on admin
  • auto create admin test user from .env.test data
• vitest with bun vs node. There were bugs that are being worked on.
  • blocked by module mock support
• playwright tests using bun - blocked

Alternatives and Inspiration

• BisonApp - Worth reading why they use tRPC. I believe gql is still better for corporate projects and this is worth a read..
• T3 App - highly recommended starting point until you understand the pros/cons of other tech options
• next-13-app-router-with-trpc - some patterns to consider.
• BaseJump supabase starter

Notes

Turbo with Next.js Dev

Waiting for it to work

• issues with middleware vercel/next.js#42921
• issues with next-intl amannn/next-intl#250
• general vercel/next.js#49174

Bun vs pnpm

Recommend pnpm for projects that need stability.
Bun is worth trying out for personal R&D and may be the future of node in a year.

Deployment

Strongly recommend deploying to Vercel until the cost at scale is prohibitive. When you need other solutions:

• Cloud Run serverless containerized deployment

  • see cloudbuild.yaml and Dockerfile

• SST

  • for those already in and experienced with AWS.
  • next.js releases seem to constantly break latest SST release in ways that are not clearly announced.

• Cloudflare Next-On-Pages

  • ideal for static marketing sites in single language. Still maturing rapidly for anything beyond that, check their github issues.
  • next-on-pages deployed on special workers so capabilities are not always comparable to workers
  • bun limited support
  • apollo client next.js needs some tweaking issue
  • links don't seem to work unless page was SSR generated in latest testing. Possibly related to issue

Graphql playground

http://localhost:3000/api/graphql To connect authenticated: Connection Settings > Edit > Include Cookies > on

Drizzle vs Prisma

For many years I was the biggest Prisma maven. I absolutely love the prisma file format. However when trying to release a serverless backend I found it required Data Proxy which I was not comfortable with.

Database type

CockroachDB was chosen for combination of free tier, postgres compatability, and ultimate scalability. Some cons:

• it doesn't offer direct edge compatability
• it isn't officially supported in drizzle yet. Migrations with DO $$ need to be manually converted to IF NOT EXISTS until issue is fixed.

Alternatives:

• Supabase - Wanted something beyond vanilla postgres on backend.
• Neon - love the serverless, branching model, and edge support. Doesn't yet offer in place version upgrades and not interested in doing export/import in production.
• Cloudflare D1 - waiting until it is GA and offers bottomless storage for further consideration.

To allow the same kube context to work on the host and the container:

Add this to hosts 127.0.0.1 kubernetes.docker.internal

Auth

To switch to firebaseui this might be relevant: firebase/firebaseui-web-react#173

Alternatives:

• Next-Auth - Doesn't seem to work cross-platform like React-Native which is critical to me for future safety.
• Clerk - didn't work for me out of the box. issue
• Supabase - didn't feel comfortable proceeding with it. Here is a post with some similar feelings for consideration.

Favicon

this is what I use to generate quick ones: https://realfavicongenerator.net/ I was using next.js app directory conversion but it was adding startup time.

pg module instead of postgres.js

If you do want pg, note this issue that needed manual patching at time of writing: brianc/node-postgres#2980 (comment)

Git branches cleanup

I am now using Graphite.dev to manage branches, commits, and PR. I highly recommend it for personal use and small teams.

Before to cleanup branches, I was using this alias: git config --global alias.branch-prune '!git fetch -p && for b in $(git for-each-ref --format='\''%(if:equals=[gone])%(upstream:track)%(then)%(refname:short)%(end)'\'' refs/heads); do git branch -d $b; done' Then run this to delete them safely git branch-prune Reference https://stackoverflow.com/a/61204370/1502448

Contributing

Feel free to PR anything that you feel is best practice. Please include changeset with any PR.