OpenAlternative Deployment and Usage Guide

1. Prerequisites

Runtime & Tools:

• Node.js (v18 or later) - Required for Next.js development
• npm or yarn or pnpm - Package manager
• Git - Version control
• Modern web browser - For viewing the application

Accounts (Optional):

• GitHub account - For contributing to the repository
• Vercel account (recommended) - For easy deployment
• Netlify account - Alternative deployment platform

Note: This project is a curated list presented as a static website. No database or backend server is required for basic usage.

2. Installation

Clone the repository:

git clone https://github.com/piotrkulpinski/openalternative.git
cd openalternative

Install dependencies:

# Using npm
npm install

# Using yarn
yarn install

# Using pnpm
pnpm install

Verify installation:

# Check Node.js version
node --version

# Verify dependencies are installed
npm list --depth=0

3. Configuration

Environment Variables: Create a .env.local file in the root directory for local development:

# Next.js environment variables
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_SITE_NAME=OpenAlternative

# Analytics (optional)
NEXT_PUBLIC_GA_TRACKING_ID=your-ga-id
NEXT_PUBLIC_PLAUSIBLE_DOMAIN=your-domain

# API keys for any integrations (if added later)
NEXT_PUBLIC_API_KEY=your-api-key

Project Structure Configuration: The main configuration files are:

• package.json - Dependencies and scripts
• next.config.js - Next.js configuration
• tailwind.config.js - Tailwind CSS configuration (if using)
• tsconfig.json - TypeScript configuration (if using)

Data Configuration: The curated list data is stored in markdown files or JSON files in the repository. To modify the list:

1. Locate the data files (typically in /data/ or /content/ directories)
2. Edit using the existing format
3. Follow the contribution guidelines in the README

4. Build & Run

Development Mode:

# Start development server
npm run dev
# or
yarn dev
# or
pnpm dev

The application will be available at http://localhost:3000. Hot reload is enabled for development.

Build for Production:

# Build the application
npm run build
# or
yarn build
# or
pnpm build

Run Production Build:

# Start the production server
npm start
# or
yarn start
# or
pnpm start

Other Useful Scripts:

# Lint code
npm run lint

# Type checking (if using TypeScript)
npm run type-check

# Run tests (if configured)
npm test

5. Deployment

Vercel (Recommended for Next.js):

1. Push your code to GitHub
2. Sign up/login to Vercel
3. Import your repository
4. Configure build settings:
   • Build Command: npm run build or yarn build
   • Output Directory: .next
   • Install Command: npm install or yarn install
5. Add environment variables in Vercel dashboard
6. Deploy

Netlify:

1. Push your code to GitHub
2. Sign up/login to Netlify
3. Click "New site from Git"
4. Select your repository
5. Configure build settings:
   • Build Command: npm run build or yarn build
   • Publish Directory: out (if static export) or .next (if server)
6. Add environment variables
7. Deploy

Static Export (for any static hosting):

# Build static files
npm run export
# or add to package.json: "export": "next build && next export"

# The static files will be in the /out directory

Docker Deployment: Create a Dockerfile:

FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:18-alpine AS runner
WORKDIR /app
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json
COPY --from=builder /app/public ./public

EXPOSE 3000
CMD ["npm", "start"]

Build and run:

docker build -t openalternative .
docker run -p 3000:3000 openalternative

Traditional Hosting:

• Requirements: Node.js runtime on server
• Process Manager: Use PM2 for production

npm install -g pm2
pm2 start npm --name "openalternative" -- start
pm2 save
pm2 startup

6. Troubleshooting

Common Issues:

1. Port already in use:

# Kill process on port 3000
# On Linux/Mac:
lsof -ti:3000 | xargs kill -9

# On Windows:
netstat -ano | findstr :3000
taskkill /PID [PID] /F

# Or run on different port:
PORT=3001 npm run dev

2. Build errors:

# Clear Next.js cache
rm -rf .next
rm -rf node_modules/.cache

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Check Node.js version compatibility
node --version

3. Module not found errors:

# Ensure all dependencies are installed
npm install

# Check for missing peer dependencies
npm ls

# Clear npm cache
npm cache clean --force

4. Environment variables not loading:

• Ensure .env.local is in root directory
• Variable names must start with NEXT_PUBLIC_ for client-side access
• Restart development server after adding new variables

5. Slow builds:

# Enable build caching
# Add to next.config.js:
experimental: {
  turbo: true
}

# Or use turbo build
npm install --save-dev @vercel/turbopack-next

6. TypeScript errors (if using TypeScript):

# Check TypeScript configuration
npx tsc --noEmit

# Update TypeScript definitions
npm install --save-dev @types/node @types/react @types/react-dom

Getting Help:

• Check existing issues on GitHub
• Review Next.js documentation at nextjs.org/docs
• For contribution questions, refer to the repository's README for guidelines

Performance Optimization:

• Use next/image for optimized images
• Implement incremental static regeneration (ISR) for dynamic content
• Enable compression in Next.js configuration
• Use CDN for static assets