Skip to main content
This guide will help you install and run Luz de Arcanos on your local machine.

​
Prerequisites

Before you begin, ensure you have:

​
Installation

1

Clone the repository

Clone the Luz de Arcanos repository to your local machine:
git clone https://github.com/RamirezDiazCarlos/TarotWeb.git
cd TarotWeb
2

Install dependencies

Install the required packages using Bun or npm:
bun install
The project uses these core dependencies:
  • astro (v5.17.1) — Framework with SSR support
  • @astrojs/vercel (v9.0.4) — Vercel adapter for deployment
  • @google/genai (v1.42.0) — Google Gemini AI SDK
3

Configure environment variables

Create a .env file in the root directory and add your Google Gemini API key:
.env
GEMINI_API_KEY=your_api_key_here
Get your free API key from Google AI Studio. The application will not function without this key.
4

Start the development server

Run the development server:
bun dev
The application will start at http://localhost:4321 by default.
5

Make your first consultation

Open your browser and navigate to http://localhost:4321. You’ll see:
  1. A form requesting your name and question
  2. After submitting, three cards will flip to reveal your reading
  3. The AI will generate a personalized interpretation
You’re limited to 5 consultations per day. This limit is stored in localStorage and resets after 24 hours.

​
Available scripts

The package.json includes these scripts:
package.json
{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}
  • dev — Start the development server with hot reload
  • build — Build the application for production
  • preview — Preview the production build locally

​
Troubleshooting

​
API key not configured

If you see an error about GEMINI_API_KEY, ensure:
  1. Your .env file exists in the root directory
  2. The variable is named exactly GEMINI_API_KEY
  3. You’ve restarted the development server after creating the .env file

​
Rate limit errors (429)

The application automatically falls back between these Gemini models:
  1. gemini-2.5-flash (primary)
  2. gemini-2.0-flash (fallback)
  3. gemini-2.0-flash-lite (final fallback)
If all models fail, a static fallback reading is generated based on the drawn cards.

​
Client-side consultation limit

If you’ve reached the 5-consultation daily limit:
  1. Wait 24 hours for the limit to reset
  2. Or clear your browser’s localStorage for the site
  3. The limit is tracked using the key tarot_usage

​
Next steps

How it works

Understand the application flow and card drawing mechanism

View live demo

See the production version in action