Development Setup

Prerequisites

Before you begin, ensure you have the following installed on your system:

Install Node.js

Download and install Node.js (v18 or higher) from nodejs.org

node --version
npm --version

Install Git

Install Git for version control from git-scm.com

git --version

Clone the Repository

Clone the project repository to your local machine

git clone <repository-url>
cd <project-name>

Install Dependencies

Install project dependencies using your preferred package manager

npm install

yarn install

pnpm install

IDE Configuration

Visual Studio Code

VS Code is the recommended IDE for this project. Install the following extensions:

Required Extensions

ESLint - Integrates ESLint JavaScript linting
Prettier - Code formatter
TypeScript and JavaScript Language Features - Enhanced TypeScript support

Recommended Extensions

Tailwind CSS IntelliSense - Autocomplete for Tailwind classes
Auto Rename Tag - Automatically rename paired HTML/JSX tags
GitLens - Enhanced Git capabilities
Error Lens - Inline error highlighting
Path Intellisense - Autocomplete for file paths

Workspace Settings

Create a .vscode/settings.json file in your project root:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true,
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}

Commit the .vscode folder to your repository to ensure consistent settings across your team.

Environment Variables

Set up your environment variables for local development:

Copy Environment Template

cp .env.example .env.local

Configure Variables

Edit .env.local with your local configuration:

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:3000/api
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Authentication
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-key-here

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# Feature Flags
NEXT_PUBLIC_FEATURE_ANALYTICS=true

Never commit .env.local or any file containing secrets to version control. Ensure these files are listed in .gitignore.

Development Tools

Package Manager

This project uses npm as the default package manager. Use the same package manager across your team to avoid lock file conflicts.

Code Quality Tools

ESLint

Linting configuration is defined in .eslintrc.js:

module.exports = {
  extends: [
    'next/core-web-vitals',
    'plugin:@typescript-eslint/recommended',
    'prettier'
  ],
  rules: {
    '@typescript-eslint/no-unused-vars': 'error',
    '@typescript-eslint/no-explicit-any': 'warn',
    'prefer-const': 'error'
  }
}

Prettier

Formatting configuration in .prettierrc:

{
  "semi": false,
  "singleQuote": true,
  "trailingComma": "es5",
  "tabWidth": 2,
  "printWidth": 80,
  "arrowParens": "avoid"
}

Husky & Lint-Staged

Pre-commit hooks ensure code quality:

// package.json
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,mdx}": [
      "prettier --write"
    ]
  }
}

Browser DevTools

React Developer Tools

Install the React DevTools browser extension for debugging React components:

Additional DevTools

Redux DevTools

For projects using Redux, install the Redux DevTools extension to inspect state changes and time-travel debug.

// store.ts
const store = configureStore({
  reducer: rootReducer,
  devTools: process.env.NODE_ENV !== 'production'
})

TanStack Query DevTools

If using TanStack Query (React Query), the devtools are included:

import { ReactQueryDevtools } from '@tanstack/react-query-devtools'

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}

Starting Development Server

Once your environment is set up, start the development server:

npm run dev

yarn dev

pnpm dev

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

The development server includes hot module replacement (HMR), so changes are reflected immediately without a full page reload.

Troubleshooting

Port Already in Use

If port 3000 is already in use:

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use a different port
PORT=3001 npm run dev

Node Modules Issues

If you encounter dependency issues:

# Clear node_modules and lock file
rm -rf node_modules package-lock.json

# Reinstall dependencies
npm install

TypeScript Errors

If TypeScript is not recognizing types:

# Restart TypeScript server in VS Code
# Press Cmd/Ctrl + Shift + P
# Type: "TypeScript: Restart TS Server"

Getting Started

Core Concepts

Development

Guides

Prerequisites

IDE Configuration

Visual Studio Code

Required Extensions

Recommended Extensions

Workspace Settings

Environment Variables

Development Tools

Package Manager

Code Quality Tools

ESLint

Prettier

Husky & Lint-Staged

Browser DevTools

React Developer Tools

Additional DevTools

Starting Development Server

Troubleshooting

Port Already in Use

Node Modules Issues

TypeScript Errors

​Prerequisites

​IDE Configuration

​Visual Studio Code

​Required Extensions

​Recommended Extensions

​Workspace Settings

​Environment Variables

​Development Tools

​Package Manager

​Code Quality Tools

​ESLint

​Prettier

​Husky & Lint-Staged

​Browser DevTools

​React Developer Tools

​Additional DevTools

​Starting Development Server

​Troubleshooting

​Port Already in Use

​Node Modules Issues

​TypeScript Errors

Prerequisites

IDE Configuration

Visual Studio Code

Required Extensions

Recommended Extensions

Workspace Settings

Environment Variables

Development Tools

Package Manager

Code Quality Tools

ESLint

Prettier

Husky & Lint-Staged

Browser DevTools

React Developer Tools

Additional DevTools

Starting Development Server

Troubleshooting

Port Already in Use

Node Modules Issues

TypeScript Errors