Skip to content

Latest commit

 

History

History
200 lines (150 loc) · 9.71 KB

README.md

File metadata and controls

200 lines (150 loc) · 9.71 KB

Next.js Template Documentation

Overview

This Next.js template provides a comprehensive foundation for building efficient, scalable, and modern web applications. It integrates powerful technologies such as Next.js, TypeScript, React, and Tailwind CSS to ensure high performance, developer productivity, and ease of maintenance.

Table of Contents

Core Technologies

  • Next.js: A leading React framework for building fast and optimized web applications with features such as server-side rendering (SSR) and static site generation (SSG).
  • TypeScript: A statically typed superset of JavaScript that provides better tooling, error-checking, and maintainability.
  • React: A popular JavaScript library for building interactive user interfaces, known for its performance and component-based architecture.
  • Tailwind CSS: A utility-first CSS framework that simplifies responsive design and helps create modern, custom user interfaces.
  • Better Auth: The most comprehensive authentication framework for TypeScript.

Key Packages & Integrations

  • Drizzle ORM: A modern, type-safe Object-Relational Mapping (ORM) library for managing database interactions seamlessly.
  • React Query: A library for fetching, caching, and synchronizing server data in React applications.
  • PostgreSQL: An advanced, open-source relational database system that ensures data integrity and scalability.

Development Tools

  • pnpm: A fast, disk-space-efficient package manager for JavaScript and TypeScript projects.
  • ESLint: A widely-used linting tool for identifying and fixing issues in JavaScript and TypeScript code.
  • Prettier: A code formatter that helps maintain code style consistency and improves readability.

Next.jsTypeScriptReactTailwind CSSDrizzle ORMReact QueryPostgreSQLRadix UIBetter Authshadcn/uipnpmESLintPrettierWinstonReact CompilerTypeScriptReact Hook FormZod

Project Setup

Prerequisites

Before getting started, make sure that you have the following tools installed on your system:

  • Node.js 20+
  • pnpm 9+
  • PostgreSQL 16+

Installation Instructions

Follow these steps to set up the project:

  1. Clone the repository:

    git clone https://github.com/Its-Satyajit/nextjs-template.git

  2. Install dependencies:

    pnpm install

  3. Configure environment variables
    Follow the detailed instructions in the Environment Variables section.

  4. Initialize the database:

    pnpm db:push

  5. Start the development server:

    pnpm dev

Your application will be available at http://localhost:3000.

Project Structure

nextjs-template/
├── src/
│   ├── app/                  # Next.js App Router pages
│   │   ├── (auth)/           # Authentication routes
│   │   ├── (dashboard)/      # Protected dashboard routes
│   │   └── api/              # API routes
│   ├── components/           # React components
│   │   ├── custom/           # Custom components
│   │   ├── providers/        # React providers
│   │   ├── section/          # Layout sections
│   │   └── ui/               # UI components
│   ├── server/               # Server-side code
│   │   ├── Actions/          # Server actions
│   │   └── db/               # Database schemas
│   ├── lib/                  # Utility functions
│   └── styles/               # Global styles
└── [configuration files]     # Various config files

Key Features

Authentication and Authorization

  • Full authentication flow using Better Auth.
  • Built-in email verification, password reset, and role-based access control (Admin/User).
  • Middleware to protect routes and ensure data privacy.

Database Integration

  • Type-safe interactions with the database using Drizzle ORM.
  • Full support for PostgreSQL with automatic migration management and schema versioning.

UI and Responsive Design

  • Build accessible user interfaces using Radix UI and shadcn/ui.
  • Fully responsive designs powered by Tailwind CSS, with support for dark mode and custom themes.

Available Scripts

Use the following commands to manage development, database, and quality assurance tasks:

# Development
pnpm dev              # Start the development server
pnpm dev:turbo        # Start with Turbo mode
pnpm dr:build:watch   # Watch routing changes

# Database
pnpm db:generate      # Generate database schemas
pnpm db:push          # Push schema changes to the database
pnpm db:studio        # Open the database UI

# Quality Assurance
pnpm check            # Run all checks
pnpm lint:fix         # Fix linting issues
pnpm format:write     # Format the codebase

Configuration Files

Key configuration files for managing project settings:

  • next.config.ts - Configuration for Next.js.
  • drizzle.config.ts - Database settings for Drizzle ORM.
  • tailwind.config.ts - Tailwind CSS configuration for styling.
  • eslint.config.mjs - Linting rules for ESLint.

Environment Variables

Make sure to set the following environment variables in the .env file:

#Server 
NODE_ENV=development
DATABASE_URL=postgresql://postgres:password@host:5432/db
BETTER_AUTH_SECRET=secret
BETTER_AUTH_URL=http://localhost:3000
REACT_EDITOR=atom

MAIL_HOST=gmail
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=password
MAIL_FROM=[email protected]
EMAIL_VERIFICATION_CALLBACK_URL=http://localhost:3000

GITHUB_CLIENT_ID=secret
GITHUB_CLIENT_SECRET=secret

#Client
NEXT_PUBLIC_BETTER_AUTH_URL=http://localhost:3000

Troubleshooting

Common Issues

  1. Database Connection Problems

    • Ensure PostgreSQL is running and verify the DATABASE_URL.
    • Make sure the specified database exists and can be accessed.

  2. Build Failures

    • Run pnpm check to detect and fix any type errors.
    • Clear the .next directory if the build persists with errors.
    • Make sure all dependencies are up to date.

  3. Authentication Errors

    • Verify your environment variables, especially those related to authentication and email settings.
    • Clear browser cookies and try again if login issues occur.

Support and Community

License

This project is licensed under the MIT License. See the LICENSE file for more details.