> ## 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.

# Quick Start

> Get your EverShop e-commerce store up and running in minutes

## Get Started in 5 Minutes

This guide will help you quickly set up and run your EverShop application locally.

<Note>
  Before you begin, ensure you have **Node.js 18+** and **PostgreSQL 12+** installed on your system.
</Note>

## Prerequisites

Verify you have the required software:

```bash theme={null}
node --version  # Should be v18 or higher
npm --version   # Should be v9 or higher
psql --version  # Should be PostgreSQL 12 or higher
```

## Quick Setup

<Steps>
  <Step title="Clone or Navigate to Your Project">
    If you already have the project, navigate to it:

    ```bash theme={null}
    cd my-evershop-app
    ```
  </Step>

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

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

    This installs:

    * `@evershop/evershop` (v2.1.1) - Core framework
    * TypeScript and type definitions
    * Development tools
  </Step>

  <Step title="Configure Database">
    Create a `.env` file in the project root with your database credentials:

    ```bash theme={null}
    DB_HOST=localhost
    DB_PORT=5432
    DB_NAME=evershop
    DB_USER=your_username
    DB_PASSWORD=your_password
    ```

    <Warning>
      Never commit `.env` files to version control. The `.gitignore` is already configured to exclude them.
    </Warning>
  </Step>

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

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

    This command:

    * Creates database tables
    * Sets up initial data
    * Configures the system
  </Step>

  <Step title="Start Development Server">
    Launch the development server with hot reload:

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

    Your store will be available at:

    * **Storefront**: [http://localhost:3000](http://localhost:3000)
    * **Admin Panel**: [http://localhost:3000/admin](http://localhost:3000/admin)
  </Step>
</Steps>

## Available Commands

Here are the npm scripts configured in your `package.json`:

<CodeGroup>
  ```bash Development theme={null}
  # Start development server with hot reload
  npm run dev

  # Accessible at http://localhost:3000
  # Changes to code automatically reload
  ```

  ```bash Production theme={null}
  # Build the project for production
  npm run build

  # Start production server
  npm run start

  # Or combine both commands
  npm run build && npm run start
  ```

  ```bash Setup theme={null}
  # Install and initialize EverShop
  npm run setup

  # Use this for first-time setup
  ```
</CodeGroup>

## Verify Installation

Once the development server is running, verify everything works:

<Tabs>
  <Tab title="Storefront">
    Open [http://localhost:3000](http://localhost:3000) in your browser. You should see:

    * Homepage with featured products section
    * Navigation header
    * Product categories
    * Footer with store information

    The current theme (`anasuplements`) uses a green color scheme optimized for supplement products.
  </Tab>

  <Tab title="Admin Panel">
    Navigate to [http://localhost:3000/admin](http://localhost:3000/admin):

    * Log in with admin credentials (created during setup)
    * Access product management
    * Configure store settings
    * Manage orders and customers
  </Tab>

  <Tab title="API">
    Test the GraphQL API at [http://localhost:3000/graphql](http://localhost:3000/graphql):

    ```graphql theme={null}
    query {
      products(limit: 5) {
        items {
          productId
          name
          price
          description
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Project Structure Overview

Understand your project's organization:

```bash theme={null}
my-evershop-app/
├── config/                    # Configuration files
│   ├── default.json          # Base settings
│   ├── development.json      # Dev environment
│   └── production.json       # Production environment
├── extensions/               # Custom extensions
│   ├── offlinePayments/     # Payment methods
│   ├── productCatalog/      # Product features
│   └── productReviews/      # Review system
├── themes/                   # Visual themes
│   └── anasuplements/       # Current active theme
├── .env                      # Environment variables (create this)
├── .evershop/               # Build output (DO NOT EDIT)
├── node_modules/            # Dependencies (DO NOT EDIT)
└── package.json             # Project dependencies
```

<Warning>
  **Important Directories**

  * ✅ Edit: `config/`, `extensions/`, `themes/`
  * ❌ Never edit: `.evershop/`, `node_modules/`
</Warning>

## Active Extensions

Your project comes with these pre-configured extensions:

<CardGroup cols={3}>
  <Card title="offlinePayments" icon="money-bill">
    Adds cash on delivery and bank transfer payment methods
  </Card>

  <Card title="productCatalog" icon="boxes-stacked">
    Extended product information system for supplements (ingredients, benefits, dosage)
  </Card>

  <Card title="productReviews" icon="star">
    Customer review and rating system for products
  </Card>
</CardGroup>

All extensions are registered in `config/default.json`:

```json theme={null}
{
  "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"
  }
}
```

## Development Workflow

<Steps>
  <Step title="Make Changes">
    Edit files in `extensions/` or `themes/`:

    * TypeScript files (`.ts`, `.tsx`)
    * GraphQL schemas (`.graphql`)
    * Configuration files (`.json`)
  </Step>

  <Step title="Auto-Reload">
    The development server automatically detects changes and reloads:

    * Backend changes rebuild the API
    * Frontend changes update the UI
    * No manual restart needed
  </Step>

  <Step title="Test Changes">
    View your changes immediately:

    * Refresh your browser
    * Check the console for errors
    * Verify functionality
  </Step>
</Steps>

## Example: View Sample Extension

Explore the sample extension to understand the structure:

```bash theme={null}
extensions/sample/
├── src/
│   ├── api/createFoo/
│   │   ├── route.json                      # API route config
│   │   └── [bodyParser]createFoo.ts       # Endpoint handler
│   ├── pages/frontStore/homepage/
│   │   └── FooList.tsx                    # Page component
│   ├── crons/
│   │   └── everyMinute.ts                 # Scheduled job
│   └── bootstrap.ts                        # Extension init
├── package.json
└── tsconfig.json
```

<Accordion title="View Sample API Endpoint">
  ```typescript theme={null}
  // extensions/sample/src/api/createFoo/[bodyParser]createFoo.ts
  import { EvershopRequest, EvershopResponse } from '@evershop/evershop';

  export default (request: EvershopRequest, response: EvershopResponse, next) => {
    const { name, description } = request.body;

    if (!name || !description) {
      return response
        .status(400)
        .json({ error: 'Name and description are required' });
    }

    const newFoo = {
      id: Date.now(),
      name,
      description
    };

    response.status(201).json({
      success: true,
      data: { foo: newFoo }
    });
  };
  ```

  With route configuration:

  ```json theme={null}
  // extensions/sample/src/api/createFoo/route.json
  {
    "methods": ["POST"],
    "path": "/foos",
    "access": "private"
  }
  ```
</Accordion>

## Common Issues

<AccordionGroup>
  <Accordion title="Port 3000 already in use">
    If port 3000 is occupied, you can change it in `config/default.json`:

    ```json theme={null}
    {
      "system": {
        "port": 3001
      }
    }
    ```
  </Accordion>

  <Accordion title="Database connection error">
    Verify your `.env` file has correct credentials:

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

    # Test connection
    psql -h localhost -U your_username -d evershop
    ```
  </Accordion>

  <Accordion title="Module not found errors">
    Reinstall dependencies:

    ```bash theme={null}
    rm -rf node_modules package-lock.json
    npm install
    ```
  </Accordion>

  <Accordion title="TypeScript compilation errors">
    Each extension has its own `tsconfig.json`. Check for type errors:

    ```bash theme={null}
    cd extensions/yourExtension
    npm run tsc
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

Now that you have EverShop running:

<CardGroup cols={2}>
  <Card title="Installation Guide" icon="download" href="/installation">
    Learn about detailed configuration options and production setup
  </Card>

  <Card title="Development Guide" icon="code" href="/guides/creating-extensions">
    Build your first extension and customize your store
  </Card>

  <Card title="Theme Customization" icon="palette" href="/themes/overview">
    Modify the visual appearance and create custom themes
  </Card>

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

<Note>
  **Need Help?**

  Check the `context/` directory in your project root for complete technical documentation in Spanish.
</Note>