### Database Setup with Docker (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Starts a PostgreSQL instance using Docker Compose and pushes the database schema. This is the recommended method for database setup.

```bash
# Start PostgreSQL with Docker Compose
npm run docker:dev

# In another terminal, push database schema
npm run db:push
```

--------------------------------

### Start Production Environment with Docker (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Command to build and start the production environment using Docker. This setup includes optimized multi-stage builds, a non-root user, health checks, and an Alpine-based image.

```bash
# Build and start production environment
npm run docker:prod

# Features:
# - Multi-stage optimized build
# - Non-root user for security
# - Health checks
# - Minimal Alpine-based image
```

--------------------------------

### Docker Build and Run Commands (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Commands for building and running Docker images and development environments. Includes building the image, starting the development setup, and starting the production environment.

```bash
npm run docker:build # Build Docker image
npm run docker:dev   # Start development environment
npm run docker:prod  # Start production environment
```

--------------------------------

### Install Dependencies (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Installs project dependencies using npm. This command should be run after cloning the repository.

```bash
npm install
```

--------------------------------

### Manual Production Build and Start (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Commands for building the Next.js application for production and starting the production server manually.

```bash
# Build the application
npm run build

# Start the production server
npm start
```

--------------------------------

### Database Setup with Local PostgreSQL (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Sets up the database by creating a new PostgreSQL database named 'next_starter' and then pushing the schema.

```bash
# Create database and push schema
createdb next_starter
npm run db:push
```

--------------------------------

### Start Database Only with Docker (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Command to start only the PostgreSQL database container using Docker Compose.

```bash
# Start only PostgreSQL database
docker-compose up postgres -d
```

--------------------------------

### Start Development Server (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Starts the Next.js development server using Turbopack. The application will be accessible at http://localhost:3000.

```bash
npm run dev
```

--------------------------------

### Set Up Environment Variables (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Copies the example environment file to .env.local and provides a list of required environment variables for database, application URLs, authentication, and Stripe integration.

```bash
# Copy environment template
cp .env.example .env.local

# Edit .env.local with your values

# Required Environment Variables:
# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/next_starter"

# App URLs
APP_URL="http://localhost:3000"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

# NextAuth
NEXTAUTH_SECRET="your-secret-key-here"
GITHUB_ID="your-github-oauth-id"
GITHUB_SECRET="your-github-oauth-secret"

# Stripe
STRIPE_SECRET_KEY="sk_test_your-key"
STRIPE_WEBHOOK_SECRET_KEY="whsec_your-key"
STRIPE_SUBSCRIPTION_PRICE_ID="price_your-price-id"
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_your-key"
```

--------------------------------

### Available Scripts: Development (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Lists available npm scripts for development tasks, including starting the dev server, building for production, and running the production server.

```bash
npm run dev          # Start development server with Turbopack
npm run build        # Build for production
npm run start        # Start production server
npm run preview      # Build and start production server
```

--------------------------------

### Run Specific Unit Tests (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Example of how to run a specific unit test file, such as 'auth.test.ts', using npm.

```bash
npm test -- auth.test.ts
```

--------------------------------

### NextAuth.js Authentication Setup

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Configuration for NextAuth.js v5, including setup for GitHub OAuth and integration with Drizzle ORM for database session management. Shows how to protect routes using the `auth()` function.

```typescript
src/lib/auth.ts

```

```typescript
src/app/api/auth/[...nextauth]/route.ts

```

--------------------------------

### Docker Compose Development Commands

Source: https://github.com/lmaksym/next-starter/blob/main/DOCKER.md

Provides Docker Compose commands for managing the development environment, including starting and stopping services with specific configurations.

```bash
# Development
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --build
docker-compose -f docker-compose.yml -f docker-compose.dev.yml down
```

--------------------------------

### Docker Compose Production Commands

Source: https://github.com/lmaksym/next-starter/blob/main/DOCKER.md

Provides essential Docker Compose commands for managing the production environment, including starting, stopping, and viewing logs for all services.

```bash
# Production
docker-compose up --build -d
docker-compose down
docker-compose logs -f
```

--------------------------------

### Run Development Docker Environment

Source: https://github.com/lmaksym/next-starter/blob/main/DOCKER.md

Starts the Next.js development environment with hot reloading enabled using Docker Compose. This setup is ideal for local development workflows.

```bash
npm run docker:dev

# Or manually
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --build
```

--------------------------------

### Start Development Environment with Docker (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Command to launch the full development environment, including PostgreSQL and the Next.js app with hot reloading and volume mounting for live code updates.

```bash
# Start full development environment (app + database)
npm run docker:dev

# This starts:
# - PostgreSQL database with sample data
# - Next.js app with hot reloading
# - Volume mounting for live code updates
```

--------------------------------

### Docker Compose Database Commands

Source: https://github.com/lmaksym/next-starter/blob/main/DOCKER.md

Specific Docker Compose commands to manage the database service independently, allowing for targeted operations like starting only the database.

```bash
# Database only
docker-compose up postgres -d
```

--------------------------------

### Docker Commands (npm)

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Commands to start the development and production environments using Docker Compose, facilitating containerized application deployment.

```shell
npm run docker:dev

```

```shell
npm run docker:prod

```

--------------------------------

### Tag and Push Docker Image

Source: https://github.com/lmaksym/next-starter/blob/main/DOCKER.md

Details the steps for tagging a locally built Docker image with a registry-specific name and pushing it to a container registry for deployment.

```bash
# Tag for registry
docker tag next-starter:latest your-registry/next-starter:latest

# Push to registry
docker push your-registry/next-starter:latest
```

--------------------------------

### Development Commands (npm)

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Essential npm commands for running the development server, building for production, checking types, and linting the project. Ensures proper setup and code quality.

```shell
npm run dev

```

```shell
npm run build

```

```shell
npm run typecheck

```

```shell
npm run lint

```

```shell
npm run lint:fix

```

--------------------------------

### Run Specific End-to-End Tests (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Example of how to run a specific end-to-end test file, such as 'home.spec.ts', using npx Playwright.

```bash
npx playwright test home.spec.ts
```

--------------------------------

### Route Organization Example

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Demonstrates the routing structure for a Next.js application, including internationalized routes, API routes for authentication and webhooks, and SEO-related files like robots.ts and sitemap.ts.

```tree
src/app/
├── [locale]/           # Internationalized routes
│   ├── page.tsx       # Home page
│   └── layout.tsx     # Locale-specific layout
├── api/               # API routes (non-internationalized)
│   ├── auth/          # NextAuth endpoints
│   └── stripe/        # Stripe webhook handlers
├── robots.ts          # SEO robots.txt
└── sitemap.ts         # SEO sitemap
```

--------------------------------

### Jest Unit Test Setup

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Configuration for Jest unit tests, including React Testing Library. It details the testing pattern where test files mirror component structure and mentions pre-configured mocks.

```javascript
src/__tests__/unit/

```

```javascript
jest.setup.js

```

--------------------------------

### View Docker Service Logs

Source: https://github.com/lmaksym/next-starter/blob/main/DOCKER.md

Demonstrates how to view logs for specific Docker services or all services managed by Docker Compose, crucial for debugging running applications.

```bash
# Application logs
docker-compose logs -f nextjs

# Database logs
docker-compose logs -f postgres

# All services
docker-compose logs -f
```

--------------------------------

### Component Organization Example

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Illustrates the directory structure for organizing UI and feature-specific components within a Next.js application. It highlights the use of shadcn/ui components and specific feature components like authentication and theme switching.

```tree
src/components/
├── ui/              # shadcn/ui components (don't modify)
├── auth-controls.tsx    # Authentication-related components
├── theme-switcher.tsx   # Theme switching functionality
├── lang-switcher.tsx    # Language switching for i18n
├── stripe-button.tsx    # Stripe payment components
└── icons.tsx        # Icon definitions
```

--------------------------------

### Troubleshoot Build Errors with Args

Source: https://github.com/lmaksym/next-starter/blob/main/DOCKER.md

Provides a solution for build failures related to environment variables by ensuring all required build arguments are passed during the Docker build process.

```bash
# Ensure all required build args are provided
docker build --build-arg NEXT_PUBLIC_APP_URL=http://localhost:3000 ...
```

--------------------------------

### Troubleshoot Database Connection Issues

Source: https://github.com/lmaksym/next-starter/blob/main/DOCKER.md

Offers commands to diagnose and resolve database connection problems by checking the PostgreSQL service status and network connectivity from the application container.

```bash
# Check if PostgreSQL is running
docker-compose logs postgres

# Check network connectivity
docker-compose exec nextjs ping postgres
```

--------------------------------

### Run Production Docker Environment

Source: https://github.com/lmaksym/next-starter/blob/main/DOCKER.md

Builds and runs the Next.js application in a production-ready Docker environment using Docker Compose. It ensures all necessary services and configurations are set up for deployment.

```bash
npm run docker:prod

# Or manually
docker-compose up --build -d
```

--------------------------------

### Troubleshoot Permission Issues

Source: https://github.com/lmaksym/next-starter/blob/main/DOCKER.md

Provides a command to reset file ownership within the running Next.js container, which can resolve permission-related errors during development or build.

```bash
# Reset ownership
docker-compose exec nextjs chown -R nextjs:nodejs /app
```

--------------------------------

### Build Docker Image Manually

Source: https://github.com/lmaksym/next-starter/blob/main/DOCKER.md

Manually builds the Docker image for the Next.js application using the 'docker build' command. This allows for more control over the build process.

```bash
# Build image
docker build -t next-starter:latest .
```

--------------------------------

### Run Docker Container Manually

Source: https://github.com/lmaksym/next-starter/blob/main/DOCKER.md

Manually runs a Docker container from the built Next.js image. This command includes port mapping and environment variable configuration.

```bash
# Run container
docker run -p 3000:3000 -e DATABASE_URL=... next-starter:latest
```

--------------------------------

### Build Docker Image Only

Source: https://github.com/lmaksym/next-starter/blob/main/DOCKER.md

Builds the Docker image for the Next.js application without running it. This command is useful for CI/CD pipelines or when you want to manage container execution separately.

```bash
npm run docker:build

# Run the built image
docker run -p 3000:3000 next-starter:latest
```

--------------------------------

### Access Running Docker Container Shell

Source: https://github.com/lmaksym/next-starter/blob/main/DOCKER.md

Provides commands to gain shell access to running Docker containers, enabling direct inspection and troubleshooting of the application or database environment.

```bash
# Access running container
docker-compose exec nextjs sh

# Access database
docker-compose exec postgres psql -U postgres -d next_starter
```

--------------------------------

### Adding New Locales

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Explains the process for integrating new locales into the project's internationalization setup, involving updates to the routing configuration and message files.

```typescript
// Update locales array in src/i18n/routing.ts
// Create corresponding message file for the new locale
```

--------------------------------

### Development with Volume Mounting

Source: https://github.com/lmaksym/next-starter/blob/main/DOCKER.md

Runs the Next.js application in a development Docker container with volume mounting. This allows code changes on the host machine to be reflected immediately inside the container, enabling fast iteration.

```bash
# Development with volume mounting
docker run -p 3000:3000 -v $(pwd):/app -w /app node:24-alpine npm run dev
```

--------------------------------

### Adding New Locales for Internationalization (TypeScript)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Demonstrates how to add a new locale ('es' for Spanish) to the project's internationalization setup by modifying the routing configuration and creating a corresponding translation file.

```typescript
export const routing = defineRouting({
  locales: ['en', 'pl', 'es'], // Add 'es' for Spanish
  defaultLocale: 'en'
});
```

```json
{
  "home": {
    "title": "Hola Mundo",
    "subtitle": "Una plantilla de inicio de Next.js"
  }
}
```

--------------------------------

### Project Structure Overview

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Illustrates the directory structure of the next-starter project, highlighting key directories for Next.js App Router, components, utilities, internationalization, tests, and Docker configuration.

```tree
next-template/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── [locale]/          # Internationalized routes
│   │   └── api/               # API routes
│   ├── components/            # React components
│   │   ├── ui/               # shadcn/ui components
│   │   └── ...               # Custom components
│   ├── lib/                   # Utility functions
│   │   ├── auth.ts           # NextAuth configuration
│   │   ├── db.ts             # Database connection
│   │   └── schema.ts         # Database schema
│   └── i18n/                  # Internationalization
├── messages/                  # Translation files
├── drizzle/                   # Database migrations
├── __tests__/                 # Test files
└── docker-compose.yml         # Docker configuration
```

--------------------------------

### Run Unit Tests (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Commands to execute unit tests for the project. Includes running all tests and running tests in watch mode for continuous feedback.

```bash
npm test             # Run unit tests
npm run test:watch   # Run tests in watch mode
```

--------------------------------

### Docker Production Deployment (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Commands for deploying the application using Docker in a production environment. Includes building and running with Docker Compose, or manually building and running the container with environment variables.

```bash
# Build and run with Docker Compose
npm run docker:prod

# Or manually
docker build -t next-starter .
docker run -p 3000:3000 --env-file .env.local next-starter
```

--------------------------------

### Database Migration Commands (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Commands for managing database migrations. Includes generating new migrations, running existing migrations, pushing schema changes, and opening Drizzle Studio.

```bash
npm run db:generate  # Generate new migrations
npm run db:migrate   # Run migrations
npm run db:push      # Push schema changes (development)
npm run db:studio    # Open Drizzle Studio
```

--------------------------------

### Clone Repository (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Clones the Next.js starter template repository from GitHub. It provides instructions for both GitHub CLI and standard Git.

```bash
# Using GitHub CLI
gh repo clone lmaksym/next-starter

# Using Git
git clone https://github.com/lmaksym/next-starter.git
cd next-starter
```

--------------------------------

### Adding Shadcn/UI Components

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Shows the command to add new UI components from shadcn/ui to the project, ensuring consistency with the existing component library.

```bash
npx shadcn@latest add [component]
```

--------------------------------

### Update Database Schema and Push Changes (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Sequence of commands to update the database schema based on changes in `src/lib/schema.ts`, generate migrations, and then push these changes to the database.

```bash
npm run db:generate  # Generate new migrations
npm run db:push      # Push schema changes (development)
```

--------------------------------

### Available Scripts: Code Quality (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Lists available npm scripts for maintaining code quality, including ESLint, TypeScript type checking, and Prettier formatting checks and fixes.

```bash
npm run lint         # Run ESLint
npm run lint:fix     # Fix ESLint errors
npm run typecheck    # Run TypeScript compiler
npm run format:check # Check Prettier formatting
npm run format:write # Fix Prettier formatting
```

--------------------------------

### Database Connection and Schema Import

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Demonstrates how to import the database connection instance and schema types from dedicated utility files. This follows the project's import pattern for managing database interactions.

```typescript
import { db } from '@/lib/db';
import { schema } from '@/lib/schema';
```

--------------------------------

### Database Operations (npm)

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Commands for managing database schema changes, pushing schema updates, generating migrations, running pending migrations, and accessing Drizzle Studio for database inspection.

```shell
npm run db:push

```

```shell
npm run db:generate

```

```shell
npm run db:migrate

```

```shell
npm run db:studio

```

--------------------------------

### Run End-to-End Tests (Bash)

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Commands to execute end-to-end tests. Supports running all tests, running tests with a UI for debugging (Playwright UI), and running specific test files.

```bash
npm run e2e          # Run end-to-end tests
npm run e2e:ui       # Run e2e tests with Playwright UI
```

--------------------------------

### Testing Commands (npm)

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Commands for executing unit tests with Jest, running tests in watch mode, and performing end-to-end (e2e) tests using Playwright, including UI debugging.

```shell
npm test

```

```shell
npm run test:watch

```

```shell
npm run e2e

```

```shell
npm run e2e:ui

```

--------------------------------

### DrizzleORM Migration Configuration

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Configuration file for Drizzle ORM migrations, specifying settings for generating and running database migrations.

```typescript
drizzle.config.ts

```

--------------------------------

### UI Component Import

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Shows the standard pattern for importing UI components, specifically those provided by shadcn/ui, using the absolute import path.

```typescript
import { Button } from '@/components/ui/button';

// Usage:
<Button>Click me</Button>
```

--------------------------------

### Environment Variable Configuration

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Shows how to import environment variables from a central file `env.mjs`, emphasizing the use of absolute imports with the `@/` prefix. This ensures a single source of truth for all environment variables.

```typescript
import { env } from '@/env.mjs';

// Example usage:
const databaseUrl = env.DATABASE_URL;
```

--------------------------------

### Drizzle Kit Database Schema Management

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Indicates the use of Drizzle Kit commands for managing database schema changes. Specific commands would be executed via this tool.

```bash
# Example: Drizzle Kit commands for schema management
# npx drizzle-kit migrate
# npx drizzle-kit push
```

--------------------------------

### Drizzle ORM Database Connection

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Sets up the database connection using Drizzle ORM with the postgres.js driver, facilitating interactions with the PostgreSQL database.

```typescript
src/lib/db.ts

```

--------------------------------

### Server Actions Error Handling Pattern

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Illustrates the recommended pattern for error handling in server actions. It suggests using try/catch blocks and returning error objects instead of throwing exceptions.

```typescript
src/actions/

```

--------------------------------

### Next.js Build Command with Environment Validation Skip

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Provides the command to run the Next.js build process while skipping environment variable validation. This is useful during development or specific deployment scenarios.

```bash
SKIP_ENV_VALIDATION=true npm run build
```

--------------------------------

### Navigation Component Import

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Illustrates the correct way to import navigation components for internationalized routing. It stresses using the project's custom navigation components instead of Next.js defaults.

```typescript
import { Link } from '@/i18n/navigation';

// Usage:
<Link href="/">Home</Link>
```

--------------------------------

### Stripe Checkout UI Component

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

A reusable UI component for initiating the Stripe checkout process, likely containing a button or form to trigger payment actions.

```typescript
src/components/stripe-button.tsx

```

--------------------------------

### shadcn/ui Component Location

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Indicates the directory where pre-built shadcn/ui components are located. Users are advised not to modify these components directly.

```plaintext
src/components/ui/

```

--------------------------------

### Custom UI Component Organization

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Specifies the organization pattern for custom UI components within the project. Components are grouped by feature for better maintainability.

```plaintext
src/components/

```

--------------------------------

### Drizzle ORM Database Schema

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Defines the database schema using Drizzle ORM for PostgreSQL. Includes tables for authentication (users, accounts, sessions) and business logic, ensuring type safety.

```typescript
src/lib/schema.ts

```

--------------------------------

### Use Internationalization in Next.js Components

Source: https://github.com/lmaksym/next-starter/blob/main/README.md

Demonstrates how to use the `useTranslations` hook from `next-intl` to translate content within a React component. This is useful for creating multi-language applications.

```typescript
import {
  useTranslations
} from 'next-intl';

export function Component() {
  const t = useTranslations('home');
  return <h1>{t('title')}</h1>;
}
```

--------------------------------

### Next.js i18n Routing Configuration

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Configuration snippet for setting up internationalization (i18n) routing in Next.js. It defines supported locales and pathnames, likely used within middleware or routing logic.

```typescript
src/i18n/routing.ts

```

--------------------------------

### Stripe Payment Processing Server Actions

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Server actions responsible for handling Stripe payment logic, specifically for creating checkout sessions. This code is invoked from client components to initiate payments.

```typescript
src/actions/create-checkout-session.ts

```

--------------------------------

### T3-env Environment Variable Validation

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

Defines and validates environment variables using T3-env. This ensures type safety for server and client variables at build time, using Zod for schema validation.

```typescript
src/env.mjs

```

--------------------------------

### Stripe Webhook Handler

Source: https://github.com/lmaksym/next-starter/blob/main/CLAUDE.md

API route handler for processing Stripe events via webhooks. This endpoint receives notifications from Stripe about payment status changes and other events.

```typescript
src/app/api/stripe/webhook/route.ts

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.