syhner / next-kickstart

Next.js 14 kickstarter. Zero setup & edge ready. Take what you need: ESLint, Prettier, Tailwind, tRPC, WebSockets, Drizzle, Lucia Auth, Vitest, Testing Library, Playwright, PWA, Docker, CI, Bun

next-kickstart

Feature packed Next.js boilerplate. Zero setup. Edge ready.

Some features depend on environment variables (indicated in features list with 💡) and so require enabling. They are disabled by default so that the app runs without any setup. They can be enabled by uncommenting all lines under where @enable {feature} appears.

📚 Features

View the repository branches for other feature sets (e.g. Bun)

Core

• 🏗️ TypeScript - Configured to maximize type safety
• ⚙️ T3 Env - Environment variable validation
• 🌐 tRPC - Create end-to-end type-safe APIs that work in both client and server components
• ⚡💡 WebSockets - Real-time communication (using Pusher, but can be swapped out for alternatives)
  • 🔗 integrates with tRPC for end-to-end type-safe events
• 💽💡 Drizzle - ORM with maximal type safety
• 🔒💡 Lucia Auth - Flexible and secure authentication
  • 🔗💡 integrates with Drizzle to store auth data

Development

• 📏 ESLint - Consistent code standards
• ✨ Prettier - Consistent code styling
• 🎨 Tailwind CSS - Utility-first CSS framework
• 🧩 shadcn/ui - Components built with Radix UI and Tailwind CSS
• 📝 MDX - Use markdown with components
• 📁 Absolute imports - Easier and cleaner module imports
• 💻 VS Code configurations - Configurations for easy debugging

Testing

• 🧪 Vitest - Flexible testing framework
• 🐙 React Testing Library - Maintainable component testing
  • 🔗 integrates with Vitest as your testing framework
• 🎭 Playwright - End-to-end testing against multiple environments

Deployment

• 📊 Bundle analyzer - Analyze bundle sizes in each environment with pnpm run build:analyze
• 📦💡 next-pwa - Make your website as a progressive web app (PWA)
• 🐳 Docker - (local and production) Docker-compose and Dockerfiles for running anywhere
• 🔄 GitHub Actions - Robust CI/CD

🌱 Getting started

🚀 Option 1: Clone and deploy with Vercel

📋 Option 2: Clone and run locally

1. Fork this repository (uncheck 'Copy the main branch only` if you are interested in other branches / feature sets)
2. Clone your new repository
3. Install dependencies and run the development server

• with pnpm

  pnpm install
  pnpm run dev

• or with Docker

  docker-compose --file docker/dev/docker-compose.yml up

⚙️ Configuration

Docker

• .dockerignore
• docker/ - Dockerfile and docker-compose.yml for development and production

Drizzle

💡 (requires enabling)

• src/db/
• src/lib/db.ts
• drizzle.config.ts

ESLint

• .eslintrc.json

GitHub Actions

• .github/workflows/ci.yml - type-checking and linting (hence these errors are ignored in next.config.mjs)

Lucia Auth

💡 (requires enabling)

• src/app/api/auth
• src/app/auth
• src/components/auth.tsx
• src/db/schemas/auth.ts) store auth data in database
• src/lib/auth.ts
• types/lucia.d.ts

Examples

• src/app/examples/profile/page.tsx

MDX

• mdx-components.tsx

next-pwa

• public/icon-512x512.png
• public/manifest.json
• next.config.mjs

Playwright

• e2e/
• playwright.config.ts

Prettier

• .eslintrc.json
• .prettierignore
• .prettierrc.json

React Testing Library

• src/app/page.test.tsx
• testing/setup.ts

shadcn/ui

• src/components/providers/theme-provider.tsx
• src/components/ui/
• src/components/theme-toggle.tsx
• components.json

T3 Env

• src/env.mjs - configure environment variables
• next.config.mjs - environment variables are validated at build-time

Tailwind CSS

• src/styles/globals.css
• tailwind.config.js

tRPC

• src/app/api/trpc/[trpc]/route.ts
• src/components/providers/trpc-provider.tsx
• src/trpc/

Examples

• src/app/examples/client-component/page.tsx - use in a client component
• src/app/examples/server-component/page.tsx - use in a server component

TypeScript

• tsconfig.json - all modifications from create-next-app are explained with comments
• types/reset.d.ts - using ts-reset to increase type-safety

Vitest

• testing/setup.ts
• vitest.config.ts

VS Code

• .vscode/extensions.json - recommended workspace extensions
• .vscode/launch.json - debug configurations
• .vscode/settings.json - use project TypeScript version

WebSockets with Pusher

💡 (requires enabling)

• src/hooks/useEvent.ts
• src/lib/events.ts
• src/trpc/methods.ts

Examples

• src/app/examples/websockets/page.tsx

next-kickstart's Issues

Get to full Bun compatability

Some features were removed in the bun branch to get things working. These features are desired, so we will need to get these working / made compatible. There is some context given in the commit messages. From highest to lowest priority:

• Working Docker images (commit where related files were changed)
• Working unit tests when next-auth is enabled (may require mocking 'next-auth' like in the main branch)
• Working component tests with React Testing Library (commit where related files were changed)
• Working MDX components (commit where related files were changed)
• Works as a Progressive Web App (commit where related files were changed)