Codakey
Play
← Back to european-alternatives

How to Deploy & Use european-alternatives

European Alternatives: Deployment & Usage Guide

1. Prerequisites

Before you begin, ensure you have the following installed:

Runtime & Tools:

  • Node.js 20+ (check with node --version)
  • npm (comes with Node.js, check with npm --version)
  • Git (for cloning the repository)

Optional for Development:

  • Code editor with TypeScript support (VS Code recommended)
  • Modern web browser for testing

No API keys or external accounts are required as this is a static site with locally sourced data.

2. Installation

Clone the Repository

git clone https://github.com/TheMorpheus407/european-alternatives.git
cd european-alternatives

Install Dependencies

npm install

This installs all required packages including:

  • React 19 + TypeScript
  • Vite 7 (build tool)
  • React Router v7
  • Framer Motion (animations)
  • i18next (internationalization)
  • ESLint (linting)

3. Configuration

Environment Variables

This project uses a static data architecture and doesn't require environment variables for basic operation. However, for advanced use cases:

Optional Environment Variables:

  • VITE_BASE_PATH: Set if deploying to a subdirectory (default: /)
  • VITE_DEFAULT_LANGUAGE: Override default language (default: en)

Create a .env file in the project root if needed:

VITE_BASE_PATH=/
VITE_DEFAULT_LANGUAGE=en

Data Configuration

The application data is structured in TypeScript files within src/data/:

  • src/data/categories.ts - Defines all categories and their US giant counterparts
  • src/data/alternatives.ts - Main dataset with merged alternatives
  • src/data/manualAlternatives.ts - Hand-curated entries
  • src/data/researchAlternatives.ts - Generated from research markdown
  • src/data/trustOverrides.ts - Manual trust score adjustments
  • src/data/trustWebSignals.ts - Crawled website trust signals

Internationalization

Languages are configured in src/i18n/index.ts:

  • Currently supports English (en) and German (de)
  • Add new languages by creating locale files in src/i18n/locales/
  • Update supportedLanguages array to include new language codes

4. Build & Run

Development Server

npm run dev

The development server will start at http://localhost:5173 with hot reload enabled.

Available Scripts

# Type-check and build for production
npm run build

# Preview the production build locally
npm run preview

# Run ESLint for code quality
npm run lint

# Regenerate research catalogue from markdown
npm run generate:research

# Re-crawl vendor websites for trust signals
npm run generate:trust-signals

Production Build

npm run build

The production build outputs to the dist/ directory with:

  • Minified JavaScript and CSS
  • Optimized assets
  • TypeScript type checking

Local Preview

npm run build
npm run preview

This serves the production build at http://localhost:4173 for final testing.

5. Deployment

Recommended Platforms

Based on the tech stack (React static site), these platforms work well:

1. GitHub Pages (Free)

# Build the project
npm run build

# Deploy using gh-pages package (install first: npm install -D gh-pages)
# Add to package.json scripts:
# "deploy": "gh-pages -d dist"
npm run deploy

2. Vercel (Recommended for React)

  • Connect your GitHub repository
  • Automatic deployments on push
  • Built-in CDN and HTTPS

3. Netlify

  • Drag-and-drop dist/ folder
  • Continuous deployment from Git
  • Free SSL and CDN

4. Hostinger (Used by the original project)

  • Upload dist/ contents via FTP or file manager
  • Configure custom domain if needed

5. Cloudflare Pages

  • Git integration
  • Global CDN
  • Free tier available

Deployment Steps (Generic)

  1. Build the project: npm run build
  2. Upload the contents of the dist/ directory to your hosting provider
  3. Configure your web server to serve index.html for all routes (SPA routing)
  4. Set up custom domain and HTTPS if needed

CI/CD with GitHub Actions

The project includes GitHub Actions configuration for automated testing and deployment. Check .github/workflows/ for existing workflows.

6. Troubleshooting

Common Issues

1. Node.js Version Issues

Error: Cannot find module '...' or similar

Solution: Ensure you're using Node.js 20 or higher:

node --version
# If below 20, upgrade Node.js

2. Port Already in Use

Error: listen EADDRINUSE: address already in use :::5173

Solution: Kill the process or use a different port:

# Find and kill process
lsof -ti:5173 | xargs kill -9
# OR specify different port
npm run dev -- --port 3000

3. TypeScript Errors

Type error: Property '...' does not exist on type '...'

Solution: Run type checking separately:

npx tsc --noEmit

Check src/types/index.ts for correct interface definitions.

4. Missing Dependencies

Cannot find module 'react' or similar

Solution: Reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

5. Build Failures

Error during build: Unexpected token

Solution:

  • Clear build cache: rm -rf dist/
  • Check for syntax errors: npm run lint
  • Ensure all TypeScript files compile: npx tsc

6. Routing Issues in Production Page shows 404 on refresh or direct navigation. Solution: Configure your web server to redirect all requests to index.html (SPA fallback).

7. Trust Score Generation Issues

Error in generate:trust-signals script

Solution: Check network connectivity and ensure vendor websites are accessible. The script may fail if websites block automated requests.

8. Internationalization Not Working

Translation keys missing or not changing

Solution: Verify locale files exist in src/i18n/locales/ and are properly imported in src/i18n/index.ts.

Development Tips

  • Data Updates: When adding new alternatives, update both src/data/manualAlternatives.ts and run npm run generate:research if applicable
  • Trust Scores: Manual overrides go in src/data/trustOverrides.ts
  • Categories: Add new categories in src/data/categories.ts following the existing pattern
  • Styling: The project uses custom CSS in src/index.css - no CSS framework dependencies
  • Flags: Country flags are loaded via CDN from flag-icons - ensure internet connection for development

Getting Help

  • Check existing issues: GitHub Issues
  • Review source code documentation
  • Examine the CONTRIBUTING.md for project-specific guidelines
  • Verify your setup matches the tech stack in the README
← Project overviewView alternatives to european-alternatives →