Development setup

This guide will help you set up Contafy for local development.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js 20+

Contafy requires Node.js version 20 or higher. Check your version:

node --version

If you need to install or update Node.js:

Download: nodejs.org
Version manager: Use nvm or fnm

With nvm:

nvm install 20
nvm use 20

pnpm 8+

Contafy uses pnpm as its package manager. Install pnpm:

npm install -g pnpm

Check your version:

pnpm --version

Clone the repository

Clone the Contafy repository to your local machine:

git clone https://github.com/your-org/contafy.git
cd contafy

Install dependencies

Install all project dependencies with pnpm:

pnpm install

This will:

Install all packages from package.json
Create a node_modules/ directory
Generate a pnpm-lock.yaml lock file
Set up Git hooks (if configured)

Expected output:

Progress: resolved 1234, reused 1200, downloaded 34, added 1234, done

Environment variables

Create a .env.local file in the project root:

cp .env.example .env.local

Edit .env.local with your configuration:

# API Backend URL
NEXT_PUBLIC_API_URL=http://localhost:3001

# Frontend URL (used for redirects)
NEXT_PUBLIC_FRONTEND_URL=http://localhost:3000

# Admin Discount Route (optional)
# Customize the internal admin route
ADMIN_DISCOUNT_ROUTE=internal/discount-management

Environment variable reference

Variable	Description	Required	Default
`NEXT_PUBLIC_API_URL`	Backend API base URL	Yes	`http://localhost:3001`
`NEXT_PUBLIC_FRONTEND_URL`	Frontend base URL	Yes	`http://localhost:3000`
`ADMIN_DISCOUNT_ROUTE`	Admin panel route path	No	`internal/discount-management`

Important: Variables prefixed with NEXT_PUBLIC_ are exposed to the browser.

Backend API setup

Contafy requires a backend API to function. Ensure your backend is running:

Clone the backend repository (separate repo)
Install backend dependencies
Configure backend environment variables
Start the backend server on port 3001

Refer to the backend repository’s documentation for detailed setup instructions. Verify backend is running:

curl http://localhost:3001/health

You should receive a successful response.

Run the development server

Start the Next.js development server:

pnpm dev

Expected output:

  ▲ Next.js 16.1.1
  - Local:        http://localhost:3000
  - Network:      http://192.168.1.100:3000

 ✓ Ready in 2.5s

Open http://localhost:3000 in your browser.

Alternative: Webpack mode

If you encounter issues with the default Turbopack bundler:

pnpm dev:webpack

This uses the traditional Webpack bundler instead.

Verify the setup

Check the landing page

Navigate to http://localhost:3000 You should see the Contafy landing page.

Test authentication

Navigate to http://localhost:3000/auth/login
You should see the login form
Try registering a new account at http://localhost:3000/auth/register

Check API connectivity

Open the browser console (F12) and check for any API errors. If everything is working:

No CORS errors
API requests to /backend/* are successful
Authentication flow works

Available scripts

Contafy includes several npm scripts for development:

Development

# Start development server with Turbopack (fast)
pnpm dev

# Start development server with Webpack (compatible)
pnpm dev:webpack

Production build

# Build for production
pnpm build

# Start production server (requires build first)
pnpm start

Code quality

# Run ESLint
pnpm lint

# Run TypeScript type checking
pnpm typecheck

# Run all checks (lint + typecheck + build)
pnpm verify:all

# Run CI checks (lint + typecheck only)
pnpm verify:ci

Development workflow

Typical development workflow:

Start the backend API (separate terminal)
Start the frontend dev server: pnpm dev
Make your changes to the code
Hot reload automatically updates the browser
Check for errors in terminal and browser console
Run type checking: pnpm typecheck
Run linting: pnpm lint
Commit your changes

IDE setup

VS Code (recommended)

Recommended extensions:

ESLint: dbaeumer.vscode-eslint
Prettier: esbenp.prettier-vscode
Tailwind CSS IntelliSense: bradlc.vscode-tailwindcss
TypeScript Error Translator: mattpocock.ts-error-translator

Workspace settings (.vscode/settings.json):

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

Other IDEs

Contafy works with any IDE that supports TypeScript and ESLint:

WebStorm: Built-in TypeScript and ESLint support
Sublime Text: Install LSP-typescript and LSP-eslint
Vim/Neovim: Use coc.nvim or native LSP

Troubleshooting

Port already in use

If port 3000 is already in use:

# Find the process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or use a different port
PORT=3001 pnpm dev

Module not found errors

If you see module not found errors:

# Clear node_modules and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install

TypeScript errors

If TypeScript shows errors:

# Run type checking
pnpm typecheck

# Restart TypeScript server in VS Code
# Cmd+Shift+P → "TypeScript: Restart TS Server"

API connection issues

If API requests fail:

Verify backend is running: curl http://localhost:3001/health
Check NEXT_PUBLIC_API_URL in .env.local
Check browser console for CORS errors
Verify Next.js proxy configuration in next.config.ts

Hot reload not working

If changes don’t reflect in the browser:

Check terminal for compilation errors
Refresh the browser manually
Restart the dev server: Ctrl+C then pnpm dev
Clear Next.js cache: rm -rf .next

Next steps

Now that your environment is set up:

Read Conventions to understand code standards
Explore Project Structure to navigate the codebase
Learn Data Fetching patterns
Review Architecture for system design

Getting help

If you encounter issues:

Check the troubleshooting section above
Search existing GitHub issues
Ask in the team Slack channel
Create a new GitHub issue with:
- Error message
- Steps to reproduce
- Your environment (OS, Node version, pnpm version)

See Contributing for guidelines on submitting code.

​Prerequisites

​Node.js 20+

​pnpm 8+

​Clone the repository

​Install dependencies

​Environment variables

​Environment variable reference

​Backend API setup

​Run the development server

​Alternative: Webpack mode

​Verify the setup

​Check the landing page

​Test authentication

​Check API connectivity

​Available scripts

​Development

​Production build

​Code quality

​Development workflow

​IDE setup

​VS Code (recommended)

​Other IDEs

​Troubleshooting

​Port already in use

​Module not found errors

​TypeScript errors

​API connection issues

​Hot reload not working

​Next steps

​Getting help