> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Antony-Figueroa/my-evershop-app/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Complete installation and configuration guide for EverShop e-commerce platform

## System Requirements

Before installing EverShop, ensure your system meets these requirements:

<CardGroup cols={2}>
  <Card title="Runtime" icon="node">
    **Node.js** 18.0 or higher

    ```bash theme={null}
    node --version
    ```
  </Card>

  <Card title="Database" icon="database">
    **PostgreSQL** 12.0 or higher

    ```bash theme={null}
    psql --version
    ```
  </Card>

  <Card title="Package Manager" icon="box">
    **npm** 9.0 or higher

    ```bash theme={null}
    npm --version
    ```
  </Card>

  <Card title="Build Tools" icon="hammer">
    **TypeScript** 5.9+ (included in devDependencies)
  </Card>
</CardGroup>

## Installation Steps

<Steps>
  <Step title="Install Node.js">
    Download and install Node.js from [nodejs.org](https://nodejs.org) or use a version manager:

    <Tabs>
      <Tab title="nvm (Linux/macOS)">
        ```bash theme={null}
        # Install nvm
        curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

        # Install Node.js 18
        nvm install 18
        nvm use 18
        nvm alias default 18
        ```
      </Tab>

      <Tab title="nvm-windows">
        ```bash theme={null}
        # Download from github.com/coreybutler/nvm-windows
        # Then install Node.js
        nvm install 18
        nvm use 18
        ```
      </Tab>

      <Tab title="Direct Download">
        Download the LTS version from [nodejs.org](https://nodejs.org) and run the installer.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Install PostgreSQL">
    <Tabs>
      <Tab title="Ubuntu/Debian">
        ```bash theme={null}
        # Update package list
        sudo apt update

        # Install PostgreSQL
        sudo apt install postgresql postgresql-contrib

        # Start PostgreSQL service
        sudo systemctl start postgresql
        sudo systemctl enable postgresql
        ```
      </Tab>

      <Tab title="macOS">
        ```bash theme={null}
        # Using Homebrew
        brew install postgresql@14

        # Start PostgreSQL
        brew services start postgresql@14
        ```
      </Tab>

      <Tab title="Windows">
        Download from [postgresql.org](https://www.postgresql.org/download/windows/) and run the installer.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create Database">
    Create a new PostgreSQL database for your store:

    ```bash theme={null}
    # Switch to postgres user
    sudo -u postgres psql
    ```

    ```sql theme={null}
    -- Create database
    CREATE DATABASE evershop;

    -- Create user (optional)
    CREATE USER evershop_user WITH PASSWORD 'your_secure_password';

    -- Grant privileges
    GRANT ALL PRIVILEGES ON DATABASE evershop TO evershop_user;

    -- Exit
    \q
    ```
  </Step>

  <Step title="Clone or Create Project">
    If starting from scratch:

    ```bash theme={null}
    # Create project directory
    mkdir my-evershop-app
    cd my-evershop-app

    # Initialize npm project
    npm init -y
    ```

    Or clone existing project:

    ```bash theme={null}
    git clone <your-repository-url>
    cd my-evershop-app
    ```
  </Step>

  <Step title="Install Dependencies">
    Install all required packages:

    ```bash theme={null}
    npm install
    ```

    This installs the dependencies from `package.json`:

    ```json theme={null}
    {
      "dependencies": {
        "@evershop/evershop": "2.1.1"
      },
      "devDependencies": {
        "@parcel/watcher": "2.5.6",
        "@types/config": "3.3.5",
        "@types/express": "5.0.6",
        "@types/node": "25.3.3",
        "@types/pg": "8.18.0",
        "@types/react": "19.2.14",
        "execa": "9.6.1",
        "typescript": "5.9.3"
      }
    }
    ```
  </Step>

  <Step title="Configure Environment">
    Create a `.env` file in the project root:

    ```bash theme={null}
    # Database Configuration
    DB_HOST=localhost
    DB_PORT=5432
    DB_NAME=evershop
    DB_USER=evershop_user
    DB_PASSWORD=your_secure_password

    # Server Configuration
    NODE_ENV=development
    PORT=3000

    # Session Secret (generate a random string)
    SESSION_SECRET=your_random_session_secret_here

    # Admin Credentials (for initial setup)
    ADMIN_EMAIL=admin@example.com
    ADMIN_PASSWORD=admin123
    ```

    <Warning>
      **Security**: Never commit `.env` to version control. It's already in `.gitignore`:

      ```bash theme={null}
      # .gitignore
      .env
      .env.local
      .env.*.local
      ```
    </Warning>
  </Step>

  <Step title="Run Initial Setup">
    Initialize the database and install EverShop:

    ```bash theme={null}
    npm run setup
    ```

    This command (`evershop install`) will:

    * Create all database tables
    * Set up initial data and schemas
    * Configure default settings
    * Create admin user
    * Initialize extensions
  </Step>

  <Step title="Start Development Server">
    Launch the application:

    ```bash theme={null}
    npm run dev
    ```

    The server will start at [http://localhost:3000](http://localhost:3000)

    <Note>
      Development mode includes:

      * Hot module replacement
      * Source maps for debugging
      * Verbose error messages
      * Auto-compilation of TypeScript
    </Note>
  </Step>
</Steps>

## Configuration Files

### Package Configuration

Your `package.json` defines the project structure:

```json theme={null}
{
  "name": "my-evershop-app",
  "version": "0.1.0",
  "type": "module",
  "private": true,
  "scripts": {
    "setup": "evershop install",
    "start": "evershop start",
    "build": "evershop build",
    "dev": "evershop dev"
  }
}
```

<AccordionGroup>
  <Accordion title="npm run setup">
    Runs `evershop install` to initialize the database and system. Use this once during initial installation.
  </Accordion>

  <Accordion title="npm run dev">
    Runs `evershop dev` to start the development server with hot reload. Use this during development.
  </Accordion>

  <Accordion title="npm run build">
    Runs `evershop build` to compile TypeScript and bundle assets for production.
  </Accordion>

  <Accordion title="npm run start">
    Runs `evershop start` to start the production server. Run `build` first.
  </Accordion>
</AccordionGroup>

### Store Configuration

The `config/default.json` file contains base configuration:

```json theme={null}
{
  "shop": {
    "language": "es",
    "currency": "USD"
  },
  "system": {
    "extensions": [
      {
        "name": "offlinePayments",
        "resolve": "extensions/offlinePayments",
        "enabled": true
      },
      {
        "name": "productCatalog",
        "resolve": "extensions/productCatalog",
        "enabled": true
      },
      {
        "name": "productReviews",
        "resolve": "extensions/productReviews",
        "enabled": true
      }
    ],
    "theme": "anasuplements"
  }
}
```

<Tabs>
  <Tab title="Shop Settings">
    Configure store-wide settings:

    ```json theme={null}
    {
      "shop": {
        "language": "es",      // Store language (es, en, etc.)
        "currency": "USD",     // Default currency
        "timezone": "UTC",     // Store timezone
        "weightUnit": "kg"     // Weight unit (kg, lb)
      }
    }
    ```
  </Tab>

  <Tab title="Extension Registration">
    Register and enable extensions:

    ```json theme={null}
    {
      "system": {
        "extensions": [
          {
            "name": "myExtension",
            "resolve": "extensions/myExtension",
            "enabled": true
          }
        ]
      }
    }
    ```

    * `name`: Unique extension identifier
    * `resolve`: Path to extension directory
    * `enabled`: Enable/disable extension
  </Tab>

  <Tab title="Theme Configuration">
    Set the active theme:

    ```json theme={null}
    {
      "system": {
        "theme": "anasuplements"
      }
    }
    ```

    The theme must exist in `themes/[name]/`
  </Tab>
</Tabs>

### Environment-Specific Configuration

<CodeGroup>
  ```json config/development.json theme={null}
  {
    "system": {
      "port": 3000,
      "logLevel": "debug"
    },
    "database": {
      "logging": true
    }
  }
  ```

  ```json config/production.json theme={null}
  {
    "system": {
      "port": 80,
      "logLevel": "error"
    },
    "database": {
      "logging": false,
      "pool": {
        "min": 2,
        "max": 10
      }
    }
  }
  ```
</CodeGroup>

## Extension Setup

Each extension has its own configuration:

### Extension Structure

```bash theme={null}
extensions/productCatalog/
├── src/
│   ├── graphql/
│   │   └── types/ProductExtension/
│   │       └── ProductExtension.graphql
│   └── pages/
│       └── frontStore/productView/
│           └── SupplementInfo.tsx
├── package.json
└── tsconfig.json
```

### Extension Package Configuration

```json theme={null}
{
  "name": "sample-evershop-extension",
  "version": "1.0.0",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "tsc": "tsc"
  }
}
```

### Extension TypeScript Configuration

```json theme={null}
{
  "compilerOptions": {
    "module": "NodeNext",
    "target": "ES2018",
    "lib": ["dom", "dom.iterable", "esnext"],
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true,
    "declaration": true,
    "sourceMap": true,
    "allowJs": true,
    "checkJs": false,
    "jsx": "react",
    "outDir": "./dist",
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true,
    "allowArbitraryExtensions": true,
    "strictNullChecks": true,
    "isolatedModules": false,
    "baseUrl": ".",
    "rootDir": "./src"
  },
  "include": ["src"]
}
```

## Theme Setup

### Current Theme: anasuplements

The active theme provides the visual layer:

```bash theme={null}
themes/anasuplements/
├── src/
│   └── pages/
│       ├── all/              # Global components
│       │   ├── Header.tsx
│       │   └── Footer.tsx
│       ├── homepage/         # Homepage components
│       │   ├── Hero.tsx
│       │   ├── Features.tsx
│       │   └── FeaturedProducts.tsx
│       └── account/          # Account pages
│           ├── Dashboard.tsx
│           ├── Login.tsx
│           └── Register.tsx
├── package.json
└── tsconfig.json
```

### Theme Configuration

Themes use the same TypeScript configuration as extensions. Each theme component exports:

```typescript theme={null}
// Required exports for page components
export default function MyComponent({ props }) {
  return <div>Content</div>;
}

export const layout = {
  areaId: 'content',       // Where to render
  sortOrder: 10            // Rendering order
};

export const query = `    // GraphQL query (optional)
  query {
    data {
      field
    }
  }
`;
```

<Note>
  Theme components should only contain presentation logic. Business logic belongs in extensions.
</Note>

## Production Deployment

### Build for Production

<Steps>
  <Step title="Update Production Configuration">
    Edit `config/production.json`:

    ```json theme={null}
    {
      "system": {
        "port": 80,
        "logLevel": "error"
      },
      "shop": {
        "url": "https://yourstore.com"
      }
    }
    ```
  </Step>

  <Step title="Set Environment Variables">
    Update `.env` for production:

    ```bash theme={null}
    NODE_ENV=production
    DB_HOST=your_production_host
    DB_NAME=your_production_db
    SESSION_SECRET=your_strong_random_secret
    ```
  </Step>

  <Step title="Build the Application">
    Compile all TypeScript and bundle assets:

    ```bash theme={null}
    npm run build
    ```

    This compiles:

    * All extensions to `.evershop/build/extensions/`
    * All themes to `.evershop/build/themes/`
    * Creates optimized production bundles
  </Step>

  <Step title="Start Production Server">
    ```bash theme={null}
    npm run start
    ```

    Or use a process manager like PM2:

    ```bash theme={null}
    npm install -g pm2
    pm2 start "npm run start" --name evershop
    pm2 save
    pm2 startup
    ```
  </Step>
</Steps>

### Production Checklist

<AccordionGroup>
  <Accordion title="Security">
    * [ ] Strong `SESSION_SECRET` in `.env`
    * [ ] PostgreSQL users with limited privileges
    * [ ] HTTPS enabled (use reverse proxy like Nginx)
    * [ ] Firewall configured (only ports 80/443 open)
    * [ ] Regular security updates
  </Accordion>

  <Accordion title="Performance">
    * [ ] Database connection pooling configured
    * [ ] Static assets served via CDN
    * [ ] Gzip compression enabled
    * [ ] Database indexes optimized
    * [ ] Caching strategy implemented
  </Accordion>

  <Accordion title="Monitoring">
    * [ ] Error logging configured
    * [ ] Performance monitoring (APM)
    * [ ] Database backups automated
    * [ ] Uptime monitoring
    * [ ] Log rotation configured
  </Accordion>

  <Accordion title="Scalability">
    * [ ] Load balancer for multiple instances
    * [ ] Database read replicas
    * [ ] Redis for session storage
    * [ ] Message queue for async tasks
    * [ ] Auto-scaling configured
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Database Connection Failed">
    **Problem**: Cannot connect to PostgreSQL

    **Solutions**:

    ```bash theme={null}
    # Check PostgreSQL is running
    sudo systemctl status postgresql

    # Verify credentials
    psql -h localhost -U evershop_user -d evershop

    # Check .env file
    cat .env | grep DB_

    # Test connection
    pg_isready -h localhost -p 5432
    ```
  </Accordion>

  <Accordion title="Port Already in Use">
    **Problem**: Port 3000 is already occupied

    **Solutions**:

    1. Change port in `config/default.json`:

    ```json theme={null}
    {
      "system": {
        "port": 3001
      }
    }
    ```

    2. Or kill the process using port 3000:

    ```bash theme={null}
    # Find process
    lsof -i :3000

    # Kill process
    kill -9 <PID>
    ```
  </Accordion>

  <Accordion title="TypeScript Compilation Errors">
    **Problem**: Extension fails to compile

    **Solutions**:

    ```bash theme={null}
    # Navigate to extension
    cd extensions/yourExtension

    # Check TypeScript config
    cat tsconfig.json

    # Compile manually to see errors
    npx tsc

    # Clear build cache
    rm -rf dist/
    rm -rf ../../.evershop/build/
    ```
  </Accordion>

  <Accordion title="Extension Not Loading">
    **Problem**: Custom extension doesn't appear

    **Solutions**:

    1. Verify registration in `config/default.json`
    2. Check extension is enabled: `"enabled": true`
    3. Verify directory structure matches config
    4. Restart development server
    5. Check server logs for errors
  </Accordion>

  <Accordion title="GraphQL Schema Errors">
    **Problem**: GraphQL types not resolving

    **Solutions**:

    ```bash theme={null}
    # Check .graphql file syntax
    cat extensions/yourExt/src/graphql/types/YourType/YourType.graphql

    # Verify resolvers exist
    cat extensions/yourExt/src/graphql/types/YourType/YourType.resolvers.js

    # Rebuild
    npm run build
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Development Guide" icon="code" href="/guides/creating-extensions">
    Learn how to build extensions and create custom functionality
  </Card>

  <Card title="Theme Customization" icon="palette" href="/themes/overview">
    Customize the visual appearance of your store
  </Card>

  <Card title="API Reference" icon="book" href="/api/graphql/overview">
    Explore the complete API documentation
  </Card>

  <Card title="GraphQL Schema" icon="diagram-project" href="/api/graphql/overview">
    Learn about GraphQL types and queries
  </Card>
</CardGroup>

<Note>
  **Additional Resources**

  Check the `context/` directory in your project for detailed technical documentation in Spanish, including:

  * Architecture overview
  * Code standards
  * Testing guide
  * Deployment procedures
</Note>